Incoming Mapping script

In the attached script function of the Incoming Mapping you gain access to the HTTP request payload under the “data” variable and may set up any data transformation, and system API call including but not limited to: creating and updating tickets and dynamic objects, adding absences to engineers, uploading attachments.

Our system currently only supports a type-safe subset of the Python script language. For further information please refer to our Fieldcode Embedded Python API documentation.

Responses

Our system is fully asynchronous, meaning any request will be processed after the response is returned. The response is not customizable in the Mapping script and can not return additional data.

Calling an Incoming Mapping REST API endpoint will result in one of the three expected responses.

1. 1. Process started response

      Status code: 200

      {
        "message": "Process started asynchronously. Use the returned URL in the Location header to track the process state.",
        "data": null,
        "error": false,
        "correlationId": "xyz",
        "code": "M-0-030-000"
      }

      This response indicates a successful request, where both the authorization and the request body validation succeeded, creating a process in our system. You may keep track the asynchronous processing using the Location header of the response, or the Interface Monitoring panel.

1. 1. Preprocessing failed response

      Status code: 200

      {
        "message": "Process was created but preprocessing failed:\nInvalid request body! Schema violations: \n[...]",
        "data": null,
        "error": true,
        "correlationId": "xyz",
        "code": "M-0-030-000"
      }

      This response indicates an error during request body validation. This will always result in a Rejected process created in our system that may block any follow-up requests depending on the Group definition setting.

1. Unauthorized response

   Status code: 401

   {
     "message": "Unauthorized",
     "data": null,
     "error": true,
     "correlationId": "xyz",
     "code": "M-7-030-132"
   }

   This response indicates an error with your authorization process. If you get this error, make sure to double check whether your API Key query parameter or Authorization header is properly included and your Bearer token – in case of OAuth2 – is not expired. Additionally, make sure that at least one Permission of your API Key/Interface User matches the defined permissions of your endpoint.

Outgoing Mappings

In Fieldcode the Outgoing Mappings act as an alternative to webhooks. Compared to webhooks, Outgoing Mappings give you the power to completely alter and enrich our internal models via scripting, and allows you to trigger these scripts straight from your custom project workflow, exactly where you need them.

Trigger definition

An Outgoing Mapping itself defines a callback that will be available in the Workflow editor under the “Interface webhook” action. For example, to call an external system whenever your ticket reaches the Appointment status, you first need to set up an Outgoing Mapping for object type “ticket” and your desired Interface System, then add your new Outgoing Mapping to your Workflow’s “appointment” node, using the “Interface webhook” action.

Important: When a System has the “Unrestricted use” option disabled, Outgoing Mappings of that System will only work for tickets which are either outsourced to the given system (requires the “Outsourcing” System option enabled), or that were created by an Incoming Mapping of the same System.

Important: Customizing the group definition for Outgoing Mapping is currently not available. All triggered processes will be grouped under object specific queues, with the following naming pattern: {mySystem}/{myObject}:{myObjectId}
.

Outgoing Mapping script

Similarly to the Incoming Mapping, the attached script function of the Outgoing Mapping gives you access to the model of the selected object type under the “data” variable. Here you can set up any data transformation, enrichment and external API calls.

Our system currently only supports a type-safe subset of the Python script language. For further information please refer to our Fieldcode Embedded Python API documentation.

F.A.Q.

• • Q: Can I create an Incoming Mapping without authorization requirement?
    A: No, for security reasons authorization is always required. However, API Keys are included in the query parameters of the URL, making our endpoints also available to systems without proper authentication support.

• • Q: Is there a maximum request body size limit on Incoming Mappings?
    A: Our system allows up to 50 MB to be sent in a single request.

• • Q: Can I send my request body as XML?
    A: Our REST API only works with JSON objects at the moment, but we may introduce support on request.

• • Q: Can your system call our REST API using X or Y authorization method?
    A: In the Python scripts we have built-in support for Basic Auth and OAuth2 as well as API Key and Bearer token.

• • Q: Can I set up timed/scheduled interface events?
    A: No, unfortunately our Outgoing Mappings don’t support scheduled triggering currently.

• Q: Can I parse raw embedded JSON string into JSON object during mapping?
  A: JSON parsing within mappings are not directly available but will happen automatically on HTTP requests.