HomeGuidesRecipesAPI
HomeGuidesAPILog In

Sequences

πŸ“˜

Interface Feature Availability

When using Produce web interface the sequence will be claimed when shown on screen. Using Offline Apps the sequence will be claimed after submission.

Designers can define sequences, custom formats of strings, that can be leverage across SmartIQ forms.

Usage

Creating sequences requires Design Projects Role permissions.

Sequences can be used in Design via a variable question. They will be loaded and claimed following a specified pattern during run time.

The user sequences are added to the variable drop down list. Once a form instance has generated a sequence value for an answer it will be remembered and not regenerated for each call.
To get multiple numbers, use multiple answers referencing the same sequence.

Sequences have the following character limits, Name (200), Pattern (1000), Timezone (50)

Sequence loading

SmartIQ will try to only load data when it needs to, either to display to the user on-screen or to use in a document generation or an action. If data is not displayed on screen it will not be loaded, this includes invisible questions.

When something in SmartIQ evaluates the Sequence, the application fetches the next number from the database, and the database keeps track of the fact that it has handed out a number. A subsequent request will generate a different number.

🚧

Skipping sequence numbers/premature sequence loading

To guarantee consecutive sequences, DO NOT attempt to display a sequence on screen, use it in a calculation, or a variable assignment. This will allowSmartIQ to calculate the formula on transition/submission, instead of claiming the sequence on load. If a sequence is displayed on screen or used in a calculation or variable assignment, it will be claimed.

πŸ“˜

Sequence and Guid variables are reset when reloading a completed answer file

Sequence Claiming

Claiming of a value will happen more or less "as late as possible" from SmartIQ's perspective. If your Sequence value even attempts to be displayed it will be claimed. If it's only displayed after an input then it will be claimed when the input occurs. If it is only referenced in actions/documents on a submit, it will be claimed when the user submits the form and those actions are run or documents are generated.

A new value for a Sequence will be claimed if a reference to it is:

  • displayed on screen
  • used as an input to an action
  • mapped to a document placeholder
  • used in a calculation that controls visibility of a question, or controls the activation of an action or a document

Any combination of actions above will claim the value.

Generally the problem that happens with non-sequential Sequence values is a user opens the form and is shown the sequence number... but then closes the form without submitting, resulting in a claimed number that is not associated with a workflow task (and/or document generation).

There are a couple of ways to solve this:

  1. only show the sequence number in subsequent workflow states (i.e. hide it from any display in the Start state)
  2. have some kind of launcher project that uses the API to start the sequence-using form, so that you can ensure all claimed sequences relate to an in-flight task (a user can open and cancel the launcher project without claiming a value)

Create a new Sequence

  1. Navigate to SmartIQ Manage and click on Sequences on the right side menu.
  2. Click on New Sequence
  3. Provide to following information:
PropertyDescription
NameUser description of what the sequence represents
FormatPattern that the sequence number can be formatting into. If blank just a plain number will be returned from the sequence. Otherwise it will be included in the format string.
Start ValueStart sequence number.
RestartThe value of a sequence can be set to restart from 1 after a date has passed. This can be set to year, month, or day calculated in the provided timezone. This can be set to year, month, or day calculated in the provided timezone.

🚧

Restart periods

A generated sequence number may be non-unique if the restart period is smaller than the minimum time element in the pattern. For instance, if the sequence restarts monthly but only contains the {{year}} element, the sequence numbers generated in each month would match. With a pattern of ABC-{{year}}-{{num}} in 2021 and a monthly reset, the first sequence each month would both be ABC-2021-1. Adding a {{month}} element (resulting in a pattern of ABC-{{year}}-{{month}}-{{num}}) would give sequences of ABC-2021-1-1 for January, ABC-2021-2-1 for February, and so on.

Format Sequence Patterns

The following replacement tags are supported:

  • {{num}} Sequence number.
  • {{year}} Current year.
  • {{yy}} Current 2 digit year.
  • {{month}} Current month.
  • {{day}} Current day.

Replacement tags can have numeric format options. For example {{num:0000}} inserts the sequence number with leading zeros.

For the Format ABC{{year}}{{num}} the first sequence value will be "ABC20191"