Custom Data

The Itinerary related data structures, including locations, directions and the itinerary itself can provide you the ability to store custom data.

Custom data is facilitated through attributes. Each attribute that you use for custom data should be prefixed with custom/ and then contain a kebab-case field name. For example custom/my-field.

Use Case:

• Storing a reference to an ID that is meaningful to you

• Associating basic values against itinerary values

Custom data allow you to store basic JSON data but this custom data is limited to reading back the value in queries using attrs an attrValue queries. Do not store large values within the itinerary or it could reduce the performance of the application and GraphQL response rates.

Privacy, Security

The custom data element does not provide a suitable environment to store sensitive information. It may be possible to consider an encryption PKI storage, but is not recommended.

In the case that you wish to store sensitive user data, our recommendation is for you to consider storing a user reference or key (as a form of foreign key) against your created itinerary, and then join/map that sensitive information back onto your application.

Is Custom Data needed?

While it is possible to use custom data, there is also a wide range of supported structures based on numerous use cases that Alpaca has developed. These are preferable to using custom data, but if you have specific data requirements unique to your use case, you can always leverage the custom data function.

By using the standard attributes, you will have the benefit of added type validation for attributes when you persist data.

Itinerary

The below example shows storage of an attribute of "my-field" with the value of "Example Value". The value can be obtained on the Itinerary type using the attribute field "attrValue".

1mutation CreateItineraryWithCustomData {
2  # Create an Itinerary with a custom view value
3  createItinerary(
4    itinerary: {
5      title: "Example itinerary with custom data in an attribute"
6      attrs: [{ id: "custom/my-field", value: "Example Value" }]
7    }
8  ) {
9    itinerary {
10      id
11      modified
12
13      value: attrValue(id: "custom/my-field")
14    }
15  }
16}

Sandbox: Configure | Try Operation

Alternatively, you can manage custom data using an update and upsert attribute action.

1mutation UpdateItineraryWithCustomData {
2  updateItinerary(
3    id: "itinerary/ABC123"
4    itinerary: {
5      upsertAttrs: [{ id: "custom/my-field", value: "Updated Value" }]
6    }
7  ) {
8    itinerary {
9      id
10      modified
11
12      value: attrValue(id: "custom/my-field")
13    }
14  }
15}

Sandbox: Configure | Try Operation

This is also able to be associated with "ItineraryLocations" and "ItineraryDirections", providing a way to associate your own custom data to various elements within the itinerary hierarchy.

1query GetItineraryCustomFieldValue {
2  itinerary(id: "itinerary/ABC123") {
3    id
4    value: attrValue(id: "custom/my-field")
5  }
6}

Sandbox: Configure | Try Operation

If successful, the data response would look similar to:

1{
2  "data": {
3    "itinerary": {
4      "id": "itinerary/ABC123",
5      "value": "Updated Value"
6    }
7  }
8}

Finally, you can also remove attributes using the deleteAttrs which can take the name of your custom attribute.

1mutation RemoveItineraryCustomField {
2  updateItinerary(
3    id: "itinerary/ABC123"
4    itinerary: { deleteAttrs: [{ id: "custom/my-value" }] }
5  ) {
6    itinerary {
7      id
8      modified
9
10      # Null
11      value: attrValue(id: "custom/my-value")
12    }
13  }
14}

Sandbox: Configure | Try Operation

Itinerary Location

Similarly to the Itinerary actions, you can use various operations in order to manage your custom data for Itinerary Locations. The operations are "createItineraryLocation", "updateItineraryLocation" and you can query individual locations either through itinerary "children" or "descendent" queries of via the "node" query.

1mutation UpdateItineraryLocationWithCustomData {
2  updateItineraryLocation(
3    id: "itinerary/ABC123"
4    location: { upsertAttrs: [{ id: "custom/my-field", value: "A Value" }] }
5  ) {
6    itinerary {
7      id
8      modified
9
10      value: attrValue(id: "custom/my-field")
11    }
12  }
13}

Sandbox: Configure | Try Operation

External source / External reference

The external source and external source reference is a special custom field that accepts a string value.

• Use the custom/external-ref to contain a unique identifier per record

• Use the custom/external-source to attribute the identifiers to a source. This should be common and differentiate between different source locations you may have.

The external source and external reference are locations recommended for using when relating an itinerary to your own platform.

1mutation CreateItineraryWithExternalReferences {
2  createItinerary(
3    itinerary: {
4      title: "Example itinerary with reference to your website UUIDs"
5      attrs: [
6        # Use the special custom attributes for linking to your identifiers
7        { id: "custom/external-ref", value: "my-reference-UUID" }
8        { id: "custom/external-source", value: "website" }
9      ]
10    }
11  ) {
12    itinerary {
13      id
14
15      externalRef: attrValue(id: "custom/external-ref")
16      externalSource: attrValue(id: "custom/external-source")
17    }
18  }
19}

Sandbox: Configure | Try Operation

1mutation CreateItineraryLocationWithExternalReferences {
2  createItineraryLocation(
3    itineraryId: "itinerary/ABC123"
4    location: {
5      title: "My Itinerary Location"
6      place: { position: { lon: 1, lat: 2 } }
7      attrs: [
8        # Use the special custom attributes for linking to your identifiers
9        { id: "custom/external-ref", value: "my-reference-UUID" }
10        { id: "custom/external-source", value: "website" }
11      ]
12    }
13  ) {
14    location {
15      id
16
17      externalRef: attrValue(id: "custom/external-ref")
18      externalSource: attrValue(id: "custom/external-source")
19    }
20  }
21}

Sandbox: Configure | Try Operation