API

An API Job will initiate a TM API for each record identified by the job’s Entity Selection Criteria (ESC). If an Input File is specified (by an EN, Alert, or explicitly), information from the file will be used to initiate a TM API.

When ESCs are specified by the Job Definition, the ESC data will be utilized directly. There is no limit to the type of data that can be returned by either findEntities API format ESCs or SQL format ESCs. The API uses an XML template to define the structure for the API to be run. The XML template can be an external file stored in a specified location or it can be a template managed through the Template view in Transportation Smartbench. Substitutions specified in the job’s parameters control how the returned data returned is referenced and substituted in the template before calling the API. For each ESC record, the specified API will be initiated. API calls may be batched for improved performance.

When an Input File is specified for the job instance, substitutions specified in the job’s parameters control how data from the input file is referenced and substituted before calling the API. The input file should either be in a valid format to be used as the API structure, or an XSLT transform should be used to create a valid API structure.

The following Job Parameters may be specified when defining an API Job Definition:

Parameter 1 – API Name (Required): The name of the API to be run.
Parameter 2 – Batch settings (Optional): Specifies settings specific to batching of API calls. When specifying multiple settings, separate each setting with a semi-colon (;). Valid settings include “Batch” and “BatchSize”.
- Batch: If ‘Batch’ is specified, the XML generated for each record processed will be combined, and the API will be run for the combined XML. This should only be specified for APIs that support multiple entities being run with a single call. For example, processSetLoadToPlanned can set many loads to planned at the same time. This setting does not have a value. If it is omitted, then API calls are not batched and a single API call is made for each record processed.
- BatchSize: Specify the maximum number of entities that can be batched. If there are more than this number to be processed, processing will split the API calls into multiple batches. If specified, “BatchSize” must be followed by an equals sign (=), followed by an integer which is the size. If “BatchSize” is specified, “Batch” must also be specified as the first setting. Default if not specified is no limit.
Parameter 3 – Substitutions (Optional): Specifies substitutions to apply to the API XML. The XML template substitutions identify the tags in the XML template or input file to be substituted and the data to be used for the substitution. Multiple substitution definitions should be separated by a semi-colon (;). See "Substitution Definitions" below for more information about the format for defining substitutions.
Parameter 4 – XSLT Transform File (Optional): If specified, the XSLT transform file will be applied to the input XML file to transform it into a valid CIS API XML file. XSLT is a markup language for transforming XML documents.

Substitution Definitions

Substitution definitions are defined in Parameter 3 of the job definition. Multiple substitutions are separated by a semi-colon (;). Each substitution specifies the API field and the value to be substituted. The API field and the value are separated with an equals sign (=).

For example, to specify the substitution of the ShipConfirmDateTime with the current date/time, for the processStopConfirm API, you would specify:

StopConfirmData.ShipConfirmDateTime=<@CurrentDateTime@>

API Field: To specify the API field in a substitution definition, the XML hierarchy is expressed as period (.) separated parent/child names. A top level field is specified with the name of the field. A child entity is denoted by specifying the parent field name, a period (.), and then the child field name. The parent element ‘CISDocument’ is assumed and should not be specified. For example:

“StopConfirmData.ShipConfirmDateTime” specifies the API Field to substitute the value of is the ShipConfirmDateTime child of the StopConfirmData element.

Value from Input File: To specify that the value to be substituted should be referenced from the Input XML File in a substitution definition, the XML hierarchy from the Input XML file is expressed as period (.) separated parent/child names, preceded with two backwards slashes (\\). A top level field is specified with the name of the field. A child entity is denoted by specifying the parent field name, a period (.), and then the child field name. An entity attribute is denoted by specifying the field name, a period (.), and then the attribute name. No parent element is assumed. If the XML top level is ‘CISDocument’, this field should be included. For example:
- “\\CISDocument.Carrier.CarrierCode” specifies the value to be substituted is the value of the CarrierCode field that is a child of the Carrier field that is a child of the CISDocument top level structure.
- “\\LoadTendered.Carrier.POD.Value” specifies the value to be substituted is the value of the Value attribute of the POD field that is a child of the Carrier field that is a child of the LoadTendered top level structure.
Value from findEntities API ESC: To specify that the value to be substituted should be referenced from the current ESC record when the ESC is in findEntities API format, specify the member name. For example:

“SystemLoadId” specifies that the value to be substituted is the value of the SystemLoadID member for the current ESC record.

Value from SQL ESC: To specify that the value to be substituted should be referenced from the current ESC record when the ESC is in SQL format, specify the DB column name. For example:

“LD_LEG_ID” specifies that the value to be substituted is the value of the LD_LEG_ID column for the current ESC record.

Results from previous job: Attributes from the output of one job can be passed as input to the succeeding job by providing a substitution parameter that begins with \\INPUT.

Example (XML Output):

“\\INPUT.Result.Output.CISDocument.Load.ChargedAmount” specifies the value to be substituted is the value of the ChargedAmount field from the output of the previous job stored in the below format:

<Result>

<Output><![CDATA[<?xml version="1.0" encoding="UTF-8"?>

<CISDocument>

<ResponseHeader>

<CompletedSuccessfully>true</CompletedSuccessfully>

</ResponseHeader>

<Load>

<SystemLoadID>20990</SystemLoadID>

<CurrencyCode>USD</CurrencyCode>

<ChargedAmount>247.17</ChargedAmount>

...

...

</Load>

</CISDocument>]]></Output>

</Result>

Example (JSON Output)

“\\INPUT.Result.Output.shipmentIdentifiers[0].value" specifies the value to be substituted is the value of the PICKUP type shipmentIdenfiers field from the output of the previous job stored in the below format:

<?xml version="1.0" encoding="UTF-8"?>

<Result>

<CarrierID>CARRIER44</CarrierID>

<ServiceID>LTL</ServiceID>

<TenderSatus>320</TenderSatus>

<CostSystem>2498.42</CostSystem>

<StartDate>2018-04-23</StartDate>

<EndDate>2018-04-24</EndDate>

<MYBOL>1555919881708</MYBOL>

<PICKNUM>1555919881708</PICKNUM>

<Output><![CDATA[{

"shipmentIdentifiers" : [ {

"type" : "PICKUP",

"value" : "1555919881708"

}, {

"type" : "BILL_OF_LADING",

"value" : "1555919881708"

} ],

"pickupDateTime" : {

"date" : {

"year" : 2018,

"month" : 4,

"day" : 23

},

"time" : {

"hour" : 8,

"minute" : 0,

"second" : 0,

"nano" : 0

}

},

"infoMessages" : [ {

"severity" : "INFO",

"message" : "This is a mock response. No request was actually sent to the carrier, but this confirms your request was parsed by Project44 and could be sent to a carrier. To perform a live request, use cloud.p-44.com",

"source" : "SYSTEM"

} ]

}]]></Output>

</Result>

Note: Here shipmentIdentifiers is an array and [0] represents the first element in the array.
Special Values: The following special values are supported and are computed by the system at the time of substitution:
- “<@CurrentDate@>”: Specifies that the value to be substituted is the current date
- “<@CurrentDateTime@>”: Specifies that the value to be substituted is the current date and time
- “<@CurrentPlan@>”: Specifies that the value to be substituted is the current plan of the User of the job instance
Note: Substitutions in templates is not supported by API job types.

Entity Selection Criteria Usage

ESCs specified for this job type may select any number of columns or fields. The ESC is not used to specify a specific entity. Instead, the data returned by the ESC is used by the substitutions defined in Parameter 3 of the Job Definition. Each record returned by the ESC is processed separately.

Note: For more details, see the "Job Server" topic in the Transportation Manager System Administration Guide.