Event Action - Web Service : Blue Relay Support

Make a call to RESTful API Web Services to retrieve or send data such as JSON data, documents, images, and so on.

Options

Method: Select type of request from dropdown list (GET, POST, etc...)

Url: The address of the endpoint. Can make calls back to the Blue Relay server to access datasets using the Blue Relay API format. Ex: "http://127.0.0.1:8080/BlueRelayApi/dataSet/61/row"

Content: Request body as expected by the Service endpoint. Can be in raw/JSON or form data format.

Raw/JSON format:
- { "foo" : "bar" }
- { (( #foo )) : (( #bar )) }
Form Data format (to send a Blue Relay file as the request body):
- {"api_token": {"value": "7f227fe4e8ea052e4407b8a5edfe5dc6", "type":"TEXT"}, "file": {"value": "((#item.id))", "type":"FILE"}}

Headers: Optional. Used to specify network call headers. In JSON format. (Example: { "content-type" : "json" })

Success Callback: Optional. Call another Event if the returned StatusCode is successful (<300).

Error Callback: Optional. Call another Event if the StatusCode returned is an error (>= 300).

Save Response To File: Optional. Allows the user to save the response as a file which can be uploaded to Blue Relay in a callback event. The filepath is saved under context variable ((#file)) and can be accessed as an item with expression "((#expr.findByPath(#file))". Do not select this checkbox if you want to access the response values (ie json fields) within the event.

Default Response Context Variables

These context variables can be accessed by downstream actions within the event, and within any Success/Fail Callback events specified during the Web Service Action setup.

((#response)): This context variable is populated with the response of the API call. This variable will only be available if "Save Response To File" is NOT selected.

((#file)): If "Save Response To File" is selected, this context variable is created to store the filepath string where response body has been saved. However - ((#file)) is NOT accessible within the same event that called the Web Service action. A 2nd event must be created and specified as a Callback event (Success or Fail) when setting up the Web Service action. This 2nd event can access ((#file)). The file can then be permanently uploaded or copied into Blue Relay using the Upload File action with expression "((#expr.findByPath(#file))" to access the file as an item.

((#statusCode)): Contains the statusCode returned by the Web Service call. (ie 404, 300, 102, etc)

Examples:

How to receive a Web Service endpoint response to create attributes:

Web Service calls usually generate a response body. If you do not select "Save Response To File", this data will be stored in a context variable called ((#response)) which is accessible by downstream event actions. ((#response)) will also be propagated to any Callback Events selected during the Web Service event setup.

If the response body is JSON, you may access field names with the following expression:

((#response.get('jsonFieldName')))

This expression can be used in Actions such as Set Context Variable, Create Attribute, Create Tag, etc.

If the format of the response was more complex or an array, the expression may need to change in structure such as:

((#response.get(0).get('jsonFieldName')))

For nested API parameters like fetching httpStatusCode or message from the below example,

Example:

"responseResult": {

"errors": [{

"httpStatusCode": 422,

"message": "Content Object with guid null and type 6 and id 18415 not found"

}

]

}

The expression may look like this:

 ((#response.get('responseResult').get('errors')[0].get('httpStatusCode')))

(#response.get('responseResult').get('errors')[0].get('message')))

Expressions are based on Spring Expression language (SpEL), please see their documentation for more information on handling JSON.

How to send a Blue Relay file to a webservice endpoint:

This sends the file/item in context of the event to the endpoint below.

Any response from the endpoint can be captured in a response file.

Update a Blue Relay dataset row:

The following web service call uses the attributes from an item (in context of the event) and updates a dataset row with the attribute values.

How to upload a Binary Image file:

TBD

Formatting examples for Content field

Raw/JSON format:
- { "foo" : "bar" }
- { (( #foo )) : (( #bar )) }
Form Data format (to send a Blue Relay file as the request body):
- {"api_token": {"value": "7f227fe4e8ea052e4407b8a5edfe5dc6", "type":"TEXT"}, "file": {"value": "((#item.id))", "type":"FILE"}}
Blue Relay Dataset Example (to update a data set):
- {"cells":{"Name": "((#item.attributes.get("Campaign Name").value))", "Plan Year":"((#item.attributes.get("Year").value))"}}

How to call another event, which saves the API response to a file created within Blue Relay,

Select the checkbox "Save Response to File" on the Web Service event
Call another second event downstream. In the second event, the response can be accessed as the variable #file.
- ((#file)) : If a file was returned from the API call, and is a valid mime-type, then the backend will extract it using httpresponse.getEntity().getContent(); and the filepath of the file is accessible using the expression variable #file. You access the file itself through the expression "((#expr.findByPath(#file))" as seen in the above. To set it at the current event item context, set as Context Variable with key = item.
- Note, this is only possible inside a second event that's called using X Callback feature of a preliminary event.
If Save Response to File is not selected, then the overall response (regardless of outcome) is stored in a Blue Relay variable called #response. Expression language can be used to extract more information out of it. It will attempt to save the results as a json format but if it fails to parse, it will be saved with no type specified.