Defining your own data properties

In IBM® App Connect, you don't need to work with JSON to define the data properties for your own use case. You can use a property editor to specify the names and data types for your data properties, and then map to those properties like any other properties in App Connect.

Some applications specify their data properties in JavaScript Object Notation (JSON) format, which can be different from one use case to another, and so App Connect can't discover them. See the following examples.
  • A document in an IBM Cloudant database might have data properties that are specified as JSON.
    
{
  "Address": {
    "City": "London",
    "Number": 221,
    "Street": "Baker Street",
    "Zip": "NW1 5LA"
  },
  "Birthdate": "1854-01-06",
  "Name": "Mr. Sherlock Holmes"
}
  • An HTTP method might have request headers that are specified as JSON.
    
{"Accept": "application/json", "Content-Type": "application/json"}

Example 1. Using the property editor

If you want to store a user's details in a Cloudant database, the data structure of the properties might be as follows:
  • Name (string)
  • Address
    • Number (number)
    • Name (string)
    • Street (string)
    • City (string)
    • Zip (string)
  • Birthdate (date)
When you create your flow in App Connect with an action such as Create Document, you see the document object with the option for you to add properties under the heading Document data.
Screenshot that shows fields and properties to populate target fields in IBM Cloudant. One field is named Document ID. A heading named Document data has a link to add a property.

To specify a property, click Add property. You can then set the name and data type of the new property. For the first property in the previous example, you enter Name and leave the type as String.

To add the Address property, click Add property again. This time, enter the name Address, but change the type to Object. You now see a second Add property option for the Address object, which you can use to define the properties within the Address object.

After you add all the properties, your document is defined.
Figure 1. Document data definition
Screenshot shows that the Document data section includes a Name property of type string, an Address property of type object, and a Birthdate property of type date. The Address property has its own properties, named Number, Name, Street, City, and Zip.
You're now ready to use your document as if it was defined as part of the action. Click Edit mappings to save your changes and show fields for the properties that are ready to be completed. You can map to these fields from source fields of earlier nodes in the same way as for other actions in App Connect.
Figure 2. Completed mapping for the document data
Screenshot shows that the Name property has been mapped to 3 properties from a previous node in the flow: Salutation, First Name, and Last Name. For the Address, the Number property is mapped to House Number, Name is mapped to House name, Street is mapped to Street, City is mapped to City, and Zip is mapped to Zip or Postal Code. The Birthdate property is mapped to the Date of Birth property, also from a previous node in the flow.

To change or delete properties, click Edit properties to switch back to the property editor.

Note: You can change a property only if it doesn't have a value in its mapping field. Therefore, before you click Edit properties, make sure that the property's field is empty.

In the property editor, properties with mappings can't be changed.

Example 2. Using the property editor to map a "source" array to a "target" array

This example demonstrates how to use a property definition to map a "source" array from a previous node (for example, output from an event or retrieve action) to a "target" array of a similar type. Start by defining properties for your target array. For example, add a property that is named Contacts with a data type of Array of objects. Then, add nested properties that are named Name and Email with a data type of String. (You need to define a Contacts mapping that is a list of objects with name and email details.)
Figure 3. Defining properties for an array of objects
Screenshot shows the properties that were described in the previous paragraph.
You can then click Edit mappings to define mappings in the associated fields, which initially contain the text Define a parent array mapping to enable this field.
Figure 4. Initial fields for an array of objects
The screenshot is described in the previous paragraph.
To complete these fields, first specify a mapping for a collection of objects in the Contacts parent field; for example, an Attendee [] array of objects that was returned by a previous retrieve action.
Figure 5. Mapping the parent field in an array of objects
Screenshot that shows the Attendee [ ] array input for an Eventbrite "Retrieve attendees" action.
Next, specify mappings for the child fields (Name and Email). For these entries, notice that a Parent mapping item: Attendee section is included in the list of available inputs. Expand the parent section to make your selections.
Figure 6. Mapping the child fields in an array of objects
Screenshot is described in the previous paragraph.
The following example shows the completed mappings.
Figure 7. Completed mappings for an array of objects
Screenshot shows that the Contacts property is mapped to an Eventbrite Attendee. The Name property is mapped to a Name object and the Email property is mapped to an Email object from the array.

Specifying data properties as JSON

You can use JSON to define the data properties for your own use case. For example, to use JSON for a Cloudant document, first make sure that no properties are specified for "Document data", and then click Edit mappings. "Document data" is then shown as a JSON field.
Figure 8. Cloudant document "Document data" shown as a JSON field
Screenshot that shows "Document data" as a JSON field.
You can type or paste a JSON definition of your properties, and you can map fields from earlier in the flow.
Figure 9. Example of mapping into the Document data field
Screenshot that shows a JSON definition of your properties. {"Address": { "City": Mailing City, "Number":$number($substringBefore(Mailing Street, " ") ), "Street":$substringAfter(Mailing Street, " "), and so on.
Tip: To switch from editing JSON to using the property editor, first empty the JSON field and then click Add property.

Other use cases for defining your own data properties

You can also define your own data properties for the following use cases.