Transforming Fields with the API

A transformation is the result of the process of mapping fields in your connector instance resources to existing fields and objects in a mapping (mapping). After you create a mapping, you will select a connector instance, choose the resource containing the objects that you want to map to the mapping, and map fields to the mapping. The end result is a transformation of the selected objects in the connector instance.

You can test the APIs described ,in this section using our interactive documentation. Open Axway AMPLIFY, and then click API Docs in the header.

Retrieve a List of mappings

You can retrieve a list of the mappings in your organization. The list includes all fields defined in the mapping.

To retrieve a list of mappings:

  1. Call the following:

    GET /organizations/objects/definitions
  2. Continue to the next step: map fields to create a transformation.

cURL Example

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2//organizations/objects/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json'

Map Fields to Create a Default Transformation

Axway AMPLIFY provides several APIs to map resources. This section describes mapping fields for an organization-level default transformation. The result is a default transformation for all instances of a specific connector.

To map fields:

  1. Construct a JSON body as shown below. For descriptions of each parameter, see Transformation JSON Parameters.

    {
      "level":"organization",
      "vendorName":"<VENDOR_RESOURCE>",
      "fields":[
        {
          "path":"<mapping_FIELD>",
          "type":"<mapping_TYPE>",
          "vendorPath":"<VENDOR_FIELD>",
          "vendorType":"<VENDOR_TYPE>"
        }
      ]
    }
  2. Call the following, including the JSON body from the previous step:

    POST /organizations/elements/{keyOrId}/transformations/{objectName}
    Icon

    Replace {keyOrId} with the connector key or id and replace {objectName} with the name of the mapping.

Transformation JSON Parameters

Parameter Description Required (Y/N)
level The access level of the transformation, either organization, account, or instance. N. Default depends on the endpoint.
vendorName The name of the resource that contains the fields that you want to map to the mapping. N
fields

An object containing the field names and data types of the mapping and the vendor resource.

Icon
To get a list of fields in a resource, call GET hubs/{hub}/objects/{RESOURCE}/metadata.
N
path The name of the field in the mapping. Y
vendorPath The name of the field in the vendor resource. Y
type The data type of the field in the mapping.
Data types can be,booleanstring, date, and number.
N
vendorType The data type of the field at the vendor. Unless the format is date, you do not need to include this parameter. If the format is date, also include a mask. N

cURL Example

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//organizations/elements/sfdc/transformations/myContacts \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
  "level":"organization",
  "vendorName":"Contact",
  "fields":[
    {
      "type":"string",
      "path":"FirstName",
      "vendorPath":"FirstName"
    },
    {
      "type":"string",
      "path":"id",
      "vendorPath":"Id"
    },
    {
      "type":"string",
      "path":"LastName",
      "vendorPath":"LastName"
    },
    {
      "type":"date",
      "path":"birthdate",
      "vendorPath":"Birthdate",
      "vendorType":"date",
      "configuration":[

      ]
    }
  ]
}'

Map Fields at the Instance Level

Using the Axway AMPLIFY instances endpoint, you can map fields at the instance level. Mapping fields is a two-step process that includes creating an instance-level resource, and then mapping fields to it.

To create an instance level mapping and map fields to it:

  1. Construct a JSON body for the instance level mapping, as shown below (see createapi):

    {
      "fields": [
        {
          "type": "<dataType>",
          "path": "<fieldName>"
        }
      ]
    }
  2. Create mapping. Make the following API call with the JSON body from the previous step, replacing {id} with the instance id, and replacing {objectName} with the name of the mapping:

    POST /instances/{id}/objects/{objectName}/definitions
  3. Construct a JSON body to map fields to the new mapping, as shown below. For descriptions of each parameter, see Transformation JSON Parameters.

    {
      "level":"instance",
      "vendorName":"<VENDOR_RESOURCE>",
      "fields":[
        {
          "path":"<mapping_FIELD>",
          "type":"<mapping_TYPE>",
          "vendorPath":"<VENDOR_FIELD>",
          "vendorType":"<VENDOR_TYPE>"
        }
      ]
    }
  4. Map fields to the mapping. Call the following, including the JSON body from the previous step:

    POST /instances/{id}/transformations/{objectName}
    Icon

    Replace {id} with the instance id and replace {objectName} with the name of the mapping.

cURL Example

Step 1: Create the mapping

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//instances/{id}/objects/{objectName}/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
    "fields": [
      {
        "type": "string",
        "path": "title"
      }
    ]
}'

Step 2: Map fields to the mapping

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//instances/{id}/transformations/{objectName} \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
    "vendorName": "Contact",
    "level": "instance",
    "fields": [
      {
        "path": "title",
        "type":"string",
        "vendorPath": "Title"
      }
    ]
}'

Map Fields at the Account Level

Using the Axway AMPLIFY accounts endpoint, you can map fields at the account level. Mapping fields is a two-step process that includes creating an account level resource, and then mapping fields to it.

To create an account level mapping and map fields to it:

  1. Construct a JSON body for the account level mapping as shown below:

    {
      "fields":[
        {
          "type":"<dataType>",
          "path":"<fieldName>"
        }
      ]
    }
  2. Create mapping. Make one of the following API calls with the JSON body from the previous step, replacing {id} with the account id, and replacing {objectName} with the name of the mapping:

    POST /accounts/objects/{objectName}/definitions
    Icon

    Use this API call to create a mapping at the default account level.

    POST /accounts/{id}/objects/{objectName}/definitions
    Icon

    Use this API call to specify an account by id.

  3. Construct a JSON body to map fields to the new mapping, as shown below. For descriptions of each parameter, see Transformation JSON Parameters.

    {
      "level":"instance",
      "vendorName":"<VENDOR_RESOURCE>",
      "fields":[
        {
          "path":"<mapping_FIELD>",
          "type":"<mapping_TYPE>",
          "vendorPath":"<VENDOR_FIELD>",
          "vendorType":"<VENDOR_TYPE>"
        }
      ]
    }
  4. Map fields to the mapping. Call the following, including the JSON body from the previous step:

    POST /accounts/{id}/elements/{keyOrId}/transformations/{objectName}
    Icon

    Replace{id} with the instance id, replace {keyOrId} with the connector key or id, and replace {objectName} with the name of the mapping.

cURL Example

Step 1: Create the mapping (default account)

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//accounts/objects/{objectName}/definitions \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '
  {
    "fields": [
      {
        "type": "string",
        "path": "title"
      }
    ]
}'

Step 2: Create the mapping (specific account)

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//accounts/{id}/objects/{objectName}/definitions \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '
  {
    "fields": [
      {
        "type": "string",
        "path": "title"
      }
    ]
}'

Step 3: Map fields to the mapping

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//accounts/{id}/elements/{keyOrIdtransformations}/{objectName} \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
    "vendorName": "Contact",
    "level": "account",
    "fields": [
      {
        "path": "title",
        "type":"string",
        "vendorPath": "Title"
      }

}'

Map Complex Objects

You can use regular expressions as values for the JSON body parameters.

Examples:

  • Get the value of the name field from the Products array where id = 4.

    {
      "fields": [
        {
          "path": "AppleIpadName",
          "vendorPath": "Products[id=4].name"
        }
      ]
    }
  • Get the value of the name field from the Products array where id = 2.

    {
      "fields": [
        {
          "path": "AppleNewProductName",
          "vendorPath": "details.Products[?(@.id==2)].name"
        }
      ]
    }
  • Get the touchId value from the Products array with id=2, which is inside the features object.

    {
      "fields": [
        {
          "path": "AppleTouchProductId",
          "vendorPath": "Products[?(@.features.touchId==true)].id"
        }
      ]
    }
  • Get the Id value of the Products array at index 0.

    {
      "fields": [
        {
          "path": "AppleProductId",
          "vendorPath": "Products[0].id"
        }
      ]
    }
  • Get a count of the Products array.

    {
      "fields": [
        {
          "path": "AppleProductsCount",
          "vendorPath": "Products[*].size()"
        }
      ]
    }

Related Links