Solicitation SFTP

Batch Solicitation

The process flow is as follows:

• Customer creates a formatted file (csv, XLS, or XLSX) which contains required field headings and records.

• Customer uploads to Rant & Rave service via SFTP.

• Solicitation SFTP service validates and processes the batch based on the criteria set.

• Data is passed to the correct survey channel (depending on the chosen workflow) and metadata is stored in the Rant & Rave database.

• Result of the survey is logged in the database for review on request.

Access

The SFTP is made available at solicit.rantandrave.co.uk.22.

Authentication

Access to the Solicitation SFTP uses a System User account — a dedicated credential created specifically for machine-to-machine integrations. System User credentials are not shared with interactive user accounts and are managed independently. Credentials are provided securely during onboarding. Solicitation access must be enabled on the System User account by Mobile Commons during provisioning.

File Format

The file format will be restricted in the following format:

• Recipient: The target for the survey request - this is a mandatory column.

• Workflow: Enables for multiple workflows to be defined - this is a non-mandatory column - will use the project default if missing.

• Meta: A marker column to define the start of customer variable metadata - this allows for further control columns to be included later - this is a mandatory column (unless no metadata is required).

• MyMeta(1) to MyMeta(n): These are customer defined meta columns containing data to be passed through to the Rant & Rave dashboard - the column titles will match exactly the field definitions (system name) created in the Rant & Rave dashboard.

These are also several optional control columns which can be used (these columns must appear before the Meta column and can be in any order).

• Grace: For each recipient it is possible to define the minimum time )in seconds) between re-surveying a single customer - this value allows for the default period to be overridden. This is a non-mandatory column and will use the workflow or project default if missing.

• Schedule: It defines the time (in ISO8601 format) that the record should be sent - this is a non-mandatory column and will be immediate if missing.

• Window: It defines the sociable contact time window when a record is permitted to be sent. This is a non-mandatory column and will use the workflow or project default if missing.

• Priority: It defines the relative priority for a message compared with other items in the batch and other batches for the same project (lower numbers are handled before higher numbers). This is a non-mandatory column and will be "2" if missing.

• Reference: Any reference text which will be provided back in any log requests for this item. This is a non-mandatory column and will be blank if missing.

Scheduling, Sociable Hour Windows, and Grace Periods

The schedule determines (on a per-message basis) the earliest time at which an item can be processed. The message may be sent later than this if the service is busy (for example, scheduling a large batch to be sent at the same time will queue the messages).

Once the scheduled time is reached, the sociable hours are checked to ensure that the message should be sent. If it is not within the given sociable hours (either because the scheduled time was outside the hours or the size of the queue has pushed the dispatch beyond the sociable hours), the message will be re-scheduled for the next available sociable time (the reported scheduled time will still show the original schedule).

Once a message can be sent within sociable hours, the grace period is checked (as well as whether the user has opted out). If the user was contacted within the grace period (or the user is currently opted ot), the message is abandoned. Otherwise, the message is sent.

If you send multiple solicitation at the same time, it can prevent the grace period from being processed. This can result in multiple solicitations being sent to the same recipient within the grace period. To prevent this, either avoid sending solicitations in quick succession or throttle your solicitation requests when you send several at the same time.

Solicitations will not be sent outside of the specified sociable hour windows (though they may be received outside these times if, for example, a mobile phone is turned off or has no signal when the message is sent, or due to network delays).

The format for the schedule is ISO 8601 (YYYY-MM-DDThh:mm:ssZ). Fractional seconds are permitted. The format for the sociable hours range is hh:mm:ss/hh:mm:ssZ (e.g 09:00:00/21:00:00Z to limit the hours to between 9am and 9pm). Hours are between 0 and 23 (inclusive), minutes are between 0 and 59 (inclusive), seconds are between 0 and 59 (inclusive). Seconds can be omitted.

Ranges can also be combined with commas (and optional spaces) (e.g. 09:00:00/12:00:00,16:00:00/21:00:00Z to limit the hours to between 9am and midday, or 4pm and 9pm). Time ranges can overlap.

Time ranges are always taken in the forward direction (e.g. 21:00:00/03:00:00Z will create a range from 9pm through midnight to 3am). The time zone specifier (z for UTC/GMT) should only be given on the last time in the list and may be preceded by an @ symbol. A geographic time zone can also be specified (which will allow for daylight savings time, if applicable).

Example: 09:00/21:00@Europe/London.

The geographical time zones accepted can be found here (case sensitive): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

It is possible to specify days of the week: Mon/Fri 09:00:00/21:00:00, Sat 11:00:00/21:00:00@Z will use 9am to 9pm Monday to Friday, 11am to 9pm on Saturday, and never send on a Sunday. If this time range crosses midnight, it is the start of the time range which is matched to the given day of the week. Any time range which does not include a day of the week is assumed to be everyday.

Specific dates can also be given special rules. For instance, to prevent sending messages on the 1st of January, you can use: Mon/Fri 09:00/21:00, 1-Jan -@Z and to prevent sending on May Day (the first day of May) is similar: Mon/Fri 09:00/21:00, Mon1-May -@Z.

Note: The "-" is a special time range, which means no times are valid on the matching day. This is only available when specifying times for specific days.

Summary:

It is recommended to make each time range at least several hours to ensure messages will not build up due to lack of processing time.

Processing

Once a file has been processed, the records will be stored and processed using the configuration set either through passed values for the item, or using defaults configured for the workflow or project.

Uploaded files will remain visible in the root folder briefly after the upload has completed (unless the upload was aborted). Visibility of the files to other connections while they are being uploaded is not guaranteed.

Logging

Processing logs will be stored in the database structure and will be created dynamically from a request to FTP service.

Access to the logs will be through navigation of the virtual folder structure: /<project_dir>/outbound/solicitation/logs/batches/<yyyy>/<mm>/<dd>/log.txt.

Requesting this log file returms a log of all files uploaded on that day, with each assigned a UUID:

Note: The .txt version is designed o be human friendly. The same table is also available as log.csv in comma separated format.

Each upload has a log file named according to its UUID: /<project_dir>/outbound/solicitation/logs/batches/<yyyy>/<mm>/<dd>/<uuid>-log.txt.

These files contain:

Filename: myFile1.xls Uploaded: 2015-02-01T11:29:57Z

Status: Progressing

Records Found: 3

Successful: 1

Pending: 1

Failed: 1 (1 bad recipient, 0 opt-out, 0 grace not expired)

Note: The "...." includes grace and processed time.

The status of the entire file (status: header and status column in log.txt) will be one of the following:

If the file has been parsed, the headers will be followed by a single blank line followed by a table of records which were identified in the file (as above).

The status of each record will be one of the following:

If the status is Failed, the human readable failure reasons will be one of the following:

Again, this file is also available as <uuid>-log.csv, though this file only includes the records without the header information.

To reduce duplication of data, the metadata is not included in these log files. The original files are also available at: /<project_dir>/outbound/solicitation/logs/batches/<yyyy>/<mm>/<dd>/<uuid>.csv.

Here, the .csv file is whatever format was originally uploaded. These files will be available for at least 1 month after being uploaded, then may be archived/deleted manually or automatically.

For guidance on storing, rotating and revoking your API credentials, see API Security and Technical Reference.