Many MIP Advance API methods can be called successfully using the techniques we have presented in the preceding tutorials. Their parameters, if any, are simple and easily understood. Suppose, however, that you want to create or modify a record in the Fund Accounting database; the "create" and "update" API methods require much more complicated input, whose structure may depend on other parameters such as "TType" (transaction type). How are you to know how to construct a correct input object?
In this tutorial we show how to retrieve the correct input and update templates, using the example of a JV session record. The procedures for other types of records are similar.
To update a JV session record, you must first retrieve the data to be updated by sending a GET request to the /api/te/JV/sessions/{sessionId} endpoint. (Note that the last element of this URL is a session ID; if you don't already know the identifier for the session you wish to edit, you can obtain a list of JV sessions by sending a GET request to /api/te/JV/sessions.)
The output of your Get Session request is a JSON object similar to the following:
{
"fields": [
{
"SESSION_SESSIONNUMID": "JV0301"
},
{
"SESSION_STATUS": "BP"
},
{
"SESSION_POSTED_STATUS": "Posted"
},
{
"SESSION_DESCRIPTION": "Opening Balance"
},
{
"SESSION_SESSIONDATE": "2015-12-31"
}
]
}
The format of this object is identical to the format of the input object required for a session update. To perform the update, modify one or more field values and pass the object as a body parameter of your PUT request to the /api/te/jv/sessions/{sessionId} endpoint.
The API endpoint for updating a JV session is the same as for retrieving one: /api/te/jv/sessions/{sessionId}. To retrieve a session, you issue a GET request; to update it, you use PUT and include the updated data as a body parameter.
Remember, to include a body parameter in a PUT or POST request, you assign the appropriate JSON object to the request's "data" field. See Tutorial 2 for an example of how this is done in jQuery.
Suppose you want to create a new JV session record. How would you create the input parameter object for that? One way is to retrieve an existing session as we did in the previous example, replace the field values with new data, and pass the resulting object as a body parameter with your POST request to the /api/te/jv/sessions endpoint. This will work if you have a session to copy, but not if you are writing code to initially populate the database. Is there another way?
There is. The MIP Advance API provides methods to retrieve templates for creating new database records. In the case of a JV session, you would retrieve the template by sending a GET request to the /api/te/JV/sessions/templates/default endpoint. The output of this request is the following JSON object:
{
"fields": [
{
"SESSION_SESSIONNUMID": "",
"metaData": {
"boid": 0,
"data_Type": "Text",
"field_Type": "Key_Field",
"max_Length": 31,
"max_Value": 0,
"min_Value": 0,
"mask": null,
"default_Label": "Session ID",
"lookupListVariation": 0,
"flags": "Required ",
"valid_Char": "<>"
}
},
{
"SESSION_STATUS": "",
"metaData": {
"boid": 1,
"data_Type": "Look-up List",
"field_Type": "Lookup",
"max_Length": 2,
"max_Value": 0,
"min_Value": 0,
"mask": null,
"default_Label": "Status",
"lookupListVariation": 22,
"flags": "Required ",
"valid_Char": null
}
},
{
"SESSION_DESCRIPTION": "",
"metaData": {
"boid": 3,
"data_Type": "Text",
"field_Type": "Normal",
"max_Length": 60,
"max_Value": 0,
"min_Value": 0,
"mask": null,
"default_Label": "Description",
"lookupListVariation": 0,
"flags": "Clear",
"valid_Char": null
}
},
{
"SESSION_SESSIONDATE": "2016-06-01",
"metaData": {
"boid": 4,
"data_Type": "Date-Time",
"field_Type": "Normal",
"max_Length": 0,
"max_Value": 0,
"min_Value": 0,
"mask": null,
"default_Label": "Date",
"lookupListVariation": 0,
"flags": "Required ",
"valid_Char": null
}
}
]
}
The first item in each array object is the name of a field to be included in your input object, while the second ("metadata") gives you the information you need to construct a valid value for this field. To create an input parameter for your POST request, delete the "metadata" member of each array object and assign a value to the field name. The result should be a JSON object similar to the one below:
{
"fields": [
{
"SESSION_SESSIONNUMID": "NewJVSessionId"
},
{
"SESSION_STATUS": "BS"
},
{
"SESSION_DESCRIPTION": "Session Description String"
},
{
"SESSION_SESSIONDATE": "2016-6-1"
}
]
}
As in the previous example, assign the resulting parameter object to the "data" member of your POST request to the /api/te/jv/sessions endpoint. (Again, see Tutorial 2 for an example of how to assign a body parameter.)