A feature using ShipX GraphQL API. The schema for this request is the same as makeBooking.


Step 1: Add Mapping


For values in ShipX like companyUuid, addressUuid etc. where the primary key is not stored in your system, you can use the mapping interface in Manage > Portal Companies > Your Portal Company > Mapping to create a mapping.


Click on + Add Mapping and fill in the form.


Ext ID: The primary key used in your system

Booking Field Accessor: The field to replace in the booking input (without index)

ShipX Value: The value to be mapped into the booking request object

Meta (JSON): A JSON object of any metadata you wish to store.


Example:


Step 2: Sending Request


To use your mapping in your booking request, your request has to be shaped like this:


{
  // ...other fields same as makeBooking
  body: {
    query: "mutation makeBookingRequest($input: MakeBookingRequestInput!) { makeBookingRequest(input: $input) { uuid } }",
    variables: {
        input: {
        // ...other fields same as makeBooking
        _ext: {
          [key: string]: <your-mapped-key>
        }
      }
    }
  }
}


The fields in _ext will replace the fields in the input with the same key. For example:

{
  // ...other input fields
  _ext: {
    'jobs[0].trips[0].fromCompanyUuid': 'your-primary-key',
    'jobs[0].trips[0].fromCompanyUuid._meta': JSON 
  }
}

will replace the field with the mapped uuid (refer step 1) and become

{
  // ...other input fields
  jobs: [
    {
      // ...other job fields
      trips: [
        {
          // ...other trip fields
          fromCompanyUuid: 'd3110d65-6b81-4c57-bcc8-043eab5a33c6'
        }
      ]
    }
  ],
  _ext: {
    'jobs[0].trips[0].fromCompanyUuid': 'your-primary-key',
    'jobs[0].trips[0].fromCompanyUuid._meta': JSON 
  }
}


The _meta field will be used to generate the entity (company, address, etc) that is supplied if the mapping does not exist.


Note:

  1. The booking field accessor field in mapping setting should not include indexes. This is to make that key generic and usable for any job/trip in a booking.
  2. The key in _ext that maps to the booking field accessor should always be indexed if it's an array. Even with one element. This is to allow the field selection be explicit during mapping the values.
  3. uuid is compulsory for booking, each job and each trip. This will be validated in our system to make sure there's no conflicting uuid.