Managing Entitlements Sequences

Administrative APIs for managing entitlements sequences

The standard create, read, update and delete management operations are performed by calling the addEntitlementsSeqence, getEntitlementsSequence or listEntitlementsSetquences, setEntitlementsSequence and removeEntitlementsSequence APIs respectively.

Common Entitlements Sequence Types

# A transition within an entitlements sequence
type EntitlementsSequenceTransition {
  # Name of entitlements set
  entitlementsSetName: String!

  # ISO8601 period string - if not specified then this transition
  # is the final state for all users on the sequence.
  duration: String
}

# A sequence of entitlements set transitions
type EntitlementsSequence {
  # Name of the entitlements sequence
  name: String!

  # Description of the entitlements sequence
  description: String

  # Time of initial creation of an entitlements sequence in milliseconds
  # since epoch. Number is integral, float type provides sufficient
  # precision.
  createdAtEpochMs: Float!

  # Time of most recent update of an entitlements sequence in milliseconds
  # since epoch. Number is integral, float type provides sufficient
  # precision.
  updatedAtEpochMs: Float!

  # Version of the entitlements sequence. Incremented each time an update is made.
  version: Int!

  # Sequence of transitions a user will go through in order. Must not be empty.
  transitions: [EntitlementsSequenceTransition!]!
}

Add a New Entitlements Sequence

A new entitlements sequence can be added to the system by calling the addEntitlementsSequence mutation. All entitlements sets referenced by the transitions in the sequence must exist prior to adding the entitlements sequence.

# Input of a single transition within an entitlements sequence
input EntitlementsSequenceTransitionInput {
  # Name of entitlements set
  entitlementsSetName: String!

  # ISO8601 period string - if not specified then this transition
  # is the final state for all users on the sequence. If the
  # final transition has a duration, then when that duration passed
  # the user becomes unentitled for all entitlements.
  duration: String
}

# Input for the addEntitlementsSequence mutation
input AddEntitlementsSequenceInput {
  # Name of the entitlements sequence
  name: String!

  # Description of the entitlements sequence
  description: String

  # Sequence of transitions a user will go through in order. Must not be empty.
  transitions: [EntitlementsSequenceTransitionInput!]!
}

type Mutation {
  # Adds an entitlement sequence
  addEntitlementsSequence(
    input: AddEntitlementsSequenceInput!
  ): EntitlementsSequence!
}

Possible Errors

• InvalidArgumentError will be returned if the transitions array is empty or any transitions earlier in the list than the last transition do not specify a duration.

• EntitlementsSetNotFoundError will be returned if any of the referenced entitlements sets do not exist

• ServiceError will be returned for internal errors.

Adding a new entitlements sequence using SDK.

Swift

do {
    let entitlementsSetquence = try await client.addEntitlementsSequenceWithName(
        name: "premium_subscription",
        description: "Premium subscription plan",
        transitions: [
            EntitlementSequenceTransition(
                entitlementsSetName: "initial_entitlements_set",
                duration: "P3M"
            ),
            EntitlementSequenceTransition(
                entitlementsSetName: "second_entitlements_set",
                duration: "P1M"
            )
        ]
    )
} catch {    
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}

Kotlin

val entitlementsSequence =
    client.addEntitlementsSequence(
        "premium_subscription", 
        "Premium subscription plan",
        listOf(
            EntitlementSequenceTransition("initial_entitlements_set", "P3M"),
            EntitlementSequenceTransition("second_entitlements_set", "P1M")
        )
    )

TypeScript

const input = {
  name: 'premium_subscription',
  description: "Premium subscription plan',
  transitions: [
    {
      entitlementsSetName: 'initial_entitlements_set',
      duration: 'P3M',
    },
    {
      entitlementsSetName: 'second_entitlements_set',
      duration: 'P1M',
    },
  ],
}
const entitlementsSequence = await client.addEntitlementsSequence(input)

Get an Entitlements Sequence

Call the getEntitlementsSequence query to retrieve an entitlements set by name.

# Input for the getEntitlementsSequence query
input GetEntitlementsSequenceInput {
  name: String!
}

type Query {
  # Gets an entitlement sequence.
  getEntitlementsSequenc(
    input: GetEntitlementsSequenceInput!
  ): EntitlementsSequence
}

Possible Errors

• ServiceError will be returned for internal errors.

Retrieving an entitlements sequence using SDK.

Swift

do {
    let entitlementsSequence = try await client.getEntitlementsSequenceWithName(
        name: "premium_subscription_plan"
    ) 
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}

Kotlin

val entitlementsSequence =
    client.getEntitlementsSequence(
        "premium_subscription_plan"
    )

TypeScript

const input = {
  name: 'premium_subscription_plan',
}
const entitlementsSequence = await client.getEntitlementsSequence(input)

List all Entitlements Sequences

Call the listEntitlementsSequences query to list all of the entitlements setquences in the system. The results list is paginated with a page size of 10. To retrieve all results your application must implement the following algorithm.

1. Call listEntitlementsSequences query with nextToken set to null
2. If nextToken in the returned EntitlementsSequencessConnection is null, 
   there are no more results to retrieve
3. Call listEntitlementsSequences query with nextToken set to the value
   returned from the previous call
4. Go to step 2

# Pagination connection for use when listing entitlements sequences
type EntitlementsSequencesConnection {
  items: [EntitlementsSequence!]!
  nextToken: String
}

# Input for the listEntitlementsSequences query
input ListEntitlementsSequencesInput {
  token: String!
}

type Query {
# Retrieves all entitlements sequences.
listEntitlementsSequences(
  nextToken: String
): EntitlementsSequencesConnection!
}

Possible Errors

• ServiceError will be returned for internal errors.

Listing entitlements sequences using SDK.

Swift

do {
    let listOutput = try await client.listEntitlementsSequencesWithNextToken(
        nextToken: nil
    ) 
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}

Kotlin

val listOutput =
    client.listEntitlementsSequences(
        null 
    )

TypeScript

const listOutput = await client.listEntitlementsSequences()

Update an Existing Entitlements Sequence

Call the setEntitlementsSequence mutation to update the contents of an existing entitlements sequence. The updated entitlements sequence is returned.

# Input of a single transition within an entitlements sequence
input EntitlementsSequenceTransitionInput {
  # Name of entitlements set
  entitlementsSetName: String!

  # ISO8601 period string - if not specified then this transition
  # is the final state for all users on the sequence. If the
  # final transition has a duration, then when that duration passed
  # the user becomes unentitled for all entitlements.
  duration: String
}

# Input for the setEntitlementsSequence mutation
input SetEntitlementsSequenceInput {
  name: String!
  description: String
  transitions: [EntitlementSequenceTransitionInput!]!
}

type Mutation {
  # Change the entitlements set transitions represented by an entitlements sequence.
  setEntitlementsSequence(input: SetEntitlementsSequenceInput!): EntitlementsSequence!
}

Possible Errors

• InvalidArgumentError will be returned if the transitions array is empty or any transitions earlier in the list than the last transition do not specify a duration.

• EntitlementsSetNotFoundError will be returned if any of the referenced entitlements sets do not exist

• ServiceError will be returned for internal errors.

Updating an entitlements sequence using SDK.

Swift

do {
    let entitlementsSequence = try await client.setEntitlementsSequenceWithName(
        name: "premium_subscription",
        description: "Preumium subscription plan",
        transitions: [
            EntitlementSequenceTransition(
                entitlementsSetName: "initial_entitlements_set",
                duration: "P3M"
            ),
            EntitlementSequenceTransition(
                entitlementsSetName: "second_entitlements_set",
                duration: "P1M"
            )
        ]

    ) 
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}    

Kotlin

val entitlementsSequence =
    client.setEntitlementsSequence(
        "premium_subscription", 
        "Preumium subscription plan",
        listOf(
            EntitlementSequenceTransition("initial_entitlements_set", "P3M"),
            EntitlementSequenceTransition("second_entitlements_set", "P1M")
        )
    )

TypeScript

const input = {
  name: 'premium_subscription',
  description: "Premium subscription plan',
  transitions: [
    {
      entitlementsSetName: 'initial_entitlements_set',
      duration: 'P3M',
    },
    {
      entitlementsSetName: 'second_entitlements_set',
      duration: 'P1M',
    },
  ],
}
const entitlementsSequence = await client.setEntitlementsSequence(input)

Remove an Entitlements Sequence

Call the removeEntitlementsSequence mutation to remove an existing entitlements sequence by name. The removed entitlements sequence is returned on success. null is returned if the named entitlements sequence cannot be found.

# Input for the removeEntitlementsSequence mutation
input RemoveEntitlementsSequenceInput {
  name: String!
}

type Mutation {
  # Remove an entitlements sequence. Any users configured against this
  # entitlements sequence will become unentitled.
  removeEntitlementsSequence(input: RemoveEntitlementsSequenceInput!): EntitlementsSequence
}

Possible Errors

• ServiceError will be returned for internal errors.

Removing an entitlements sequence using SDK.

Swift

do {
    let entitlementsSequence = try await client.removeEntitlementsSequenceWithName(
        name: "premium_subscription"
    )
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
} 

Kotlin

val entitlementsSequence =
    client.removeEntitlementsSequence(
        "premium_subscription"
    )

TypeScript

const input = {
  name: 'premium_subscription',
}
const entitlementsSequence = await client.removeEntitlementsSequence(input)