Orbit API Configurator
The Orbit API Configurator is used to configure the OrbitAPI. Browse to the OrbitAPI directory (typically C:\inetpub\wwwroot\OrbitAPI\), right-click OrbitAPIConfigurator.exe, and select Run as administrator.
FS Config database¶
| Setting | Description |
|---|---|
| Connection string | Connection string to your configuration database, usually FS_Config |
| Edit | Opens the connection string editor |
| Test | Tests the entered connection string |
| Connection timeout (secs) | Timeout used when the OrbitAPI connects to the configuration database |
| Enable performance logging | Tick to enable performance logging to the OrbitAPI log |
| Command timeout (secs) | Timeout when running commands against the configuration database |
| Performance logging threshold | When performance logging is enabled, the threshold in milliseconds after which entries are logged |
Audience service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for FastStats jobs running an audience request |
| Base URN export path | Default path to which URNs will be exported |
| Number of VarCodes to lookup per variable | Number of variable codes to return per variable in the Orbit interface when creating an audience |
Collection service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for FastStats jobs running a collection service request |
| Return number of collection parts when viewing collections | Tick to enable retrieval of the number of collection parts |
CORS options¶
| Setting | Description |
|---|---|
| Origin | Add the URL(s) and port of the web server hosting the Orbit UI. Typically this is the same web server as the OrbitAPI. |
Core options¶
| Setting | Description |
|---|---|
| API Base URL, for API Documentation | Specify a different URL for the OrbitAPI if required, for example if a local definition is HTTP but HTTPS is being forced by a proxy server |
| Enable XML serialisation of data to/from API endpoints | Tick to enable XML serialisation to/from the API endpoints, affecting available response content types |
Dashboard service¶
| Setting | Description |
|---|---|
| Number of VarCodes to lookup per variable | Number of variable codes to return when searching variables in a dashboard |
Data licensing service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for FastStats jobs using the data licensing service |
DataView options¶
| Setting | Description |
|---|---|
| Enable "Get DataViews" API endpoint | Enables or disables the Get DataViews endpoint. Disabling this means users authenticating by username must also enter the name of the data view they wish to log into. |
| Enable "Get DataViews for domain" API endpoint | Enables or disables the Get DataViews for domain endpoint. Disabling this means users authenticating by email address must also enter the data view name. |
| Enable "Get DataViews for system name" API endpoint | Enables or disables the Get DataViews for system name endpoint. Disabling this means users must specify the data view name when sending a collection to Orbit from FastStats. |
DataView service¶
| Setting | Description |
|---|---|
| Available Systems | Names of the systems available within this DataView. Systems should use a shared global database. |
Email notification service¶
| Setting | Description |
|---|---|
| Administrator email address | Email address of the administrator of this system |
| Sender name | Name of the sender of emails from Orbit |
| Sender email address | Email address from which emails will be sent |
| Email templates directory | Name of the email templates directory (relative to the OrbitAPI directory) or the full path |
Email service¶
| Setting | Description |
|---|---|
| SMTP host | If service type is Local, the name of the SMTP host |
| SMTP port | If service type is Local, the SMTP port |
| Use SSL connection | If service type is Local, whether to use an SSL connection to the SMTP server |
| SSL certificate validation policy | If Use SSL connection is selected, the certificate validation policy |
| SMTP username | If service type is Local, the username to authenticate to the SMTP server |
| SMTP password | If service type is Local, the password for the given SMTP username |
| Local domain | If service type is Local, the local domain for the SMTP service |
Experimental options¶
Note
These options are for internal use only. No changes are required.
| Setting | Description |
|---|---|
| Show online documentation for experimental API endpoints | Enables display of experimental API endpoints in documentation |
| Show online documentation for under-development API endpoints | Shows documentation for under-development endpoints |
| Enable experimental API endpoints | Enables experimental API endpoints |
| Show online documentation for API endpoints subject to change or removal | Shows documentation for endpoints subject to change |
External login service options¶
This section is only required if you wish to use an SSO service for user authentication. Please contact Apteco for further information.
| Setting | Description |
|---|---|
| Audience | Should be set to the AptecoLoginAPI URL, e.g. https://AptecoLoginAPI/ |
| Token re-use store connection string | Optional—specify a connection string to an Orbit database (e.g. OB_Global) for load-balanced or multi-web-server configurations where token re-use must be tracked centrally |
| Ensure tables exist | When a token re-use store connection string is specified, use this to check that the required tables exist |
| Test | When a token re-use store connection string is specified, use this to test the connection string |
Note
The SSO provider issues tokens for Orbit to log in with. These tokens are tracked in memory by the Orbit API so they can only be used once before expiry. If running multiple instances of the OrbitAPI (e.g. load-balanced) or tracking token re-use across OrbitAPI restarts, specify a database to store these tokens centrally.
FacebookTokens service¶
| Setting | Description |
|---|---|
| Use Facebook tokens | Tick to enable Facebook tokens using the specified URL |
| Base URL | URL used for generating Facebook tokens |
| Auto register apps and pages | Allow Orbit to register Facebook apps and pages automatically, rather than performing manual registration through FastStats |
FastStats global database¶
| Setting | Description |
|---|---|
| Connection string | Connection string to the global database |
| Command timeout (secs) | Command timeout |
| Connection timeout (secs) | Connection timeout |
| Enable performance logging | Tick to log database queries exceeding the performance logging threshold |
| Performance logging threshold | Threshold in milliseconds after which queries are logged |
FastStats Google database¶
| Setting | Description |
|---|---|
| Connection string | Connection string to the Google database |
| Command timeout (secs) | Command timeout |
| Connection timeout (secs) | Connection timeout |
| Enable performance logging | Tick to log database queries exceeding the performance logging threshold |
| Performance logging threshold (millis) | Threshold in milliseconds after which queries are logged |
FastStats social database¶
| Setting | Description |
|---|---|
| Connection string | Connection string to the social database |
| Command timeout (secs) | Command timeout |
| Connection timeout (secs) | Connection timeout |
| Enable performance logging | Tick to log database queries exceeding the performance logging threshold |
| Performance logging threshold (millis) | Threshold in milliseconds after which queries are logged |
FastStats system database¶
| Setting | Description |
|---|---|
| Connection string | Connection string to the system database |
| Command timeout (secs) | Command timeout |
| Connection timeout (secs) | Connection timeout |
| Enable performance logging | Tick to log database queries exceeding the performance logging threshold |
| Performance logging threshold | Threshold in milliseconds after which queries are logged |
FastStatsAnalysis service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for FastStats jobs using the analysis service |
| Enable database caching | Whether to cache analysis service job results for faster performance |
| BETA: allow database caching to work with Virtual Variables (except dynamic VVs) | Beta feature |
| BETA: Allow database caching to work with Row Filters | Beta feature |
FastStatsFile service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for FastStats jobs using the FastStats File service |
| Default file read/write strategy | Choose between local temporary files (faster, on the web server) or the FastStats JobQueue (slower, not on the web server) |
FastStatsJob service¶
| Setting | Description |
|---|---|
| Maximum command size (chars) | Maximum command size in characters |
FastStatsSystem service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for FastStats jobs using the FastStats System service |
| All items cache base file path | Base directory within which SQLite stores of system structure, variables, and their contents are built |
| Use in-memory varcodes (picklist) cache | Whether to store variable information in a file-based store (the directory specified) or in memory on the web server. In-memory is faster but places more load on the web server. |
| Enable Varcodes cache population batching | Whether to allow the varcode cache to be populated at once or in batches |
| Varcodes cache population batch size | When batching is enabled, the number of varcodes processed per batch |
General settings¶
| Setting | Description |
|---|---|
| DataView Name | Name of the DataView being configured. Normally matches the FastStats system name. The active tab name refreshes when changed. |
| Enabled | Tick to enable this DataView within the OrbitAPI |
GoogleTokens service¶
| Setting | Description |
|---|---|
| Use Google tokens | Tick to enable Google tokens using the specified URL |
| Base URL | URL used for generating Google tokens |
JWT issuer options¶
| Setting | Description |
|---|---|
| Issuer | Identifies the JSON Web Token issuer. Leave as FastStatsTokenServer. |
| Audience | The recipient URL that the JWT is intended for. Change this to the fully qualified URL of the OrbitAPI, e.g. https://myserver.com/OrbitAPI |
| Secret key | A secret key used in the generation of the JWT |
Licensing service¶
| Setting | Description |
|---|---|
| Allow multiple simultaneous sessions per user | Whether more than one session is allowed per user |
LinkedInTokens service¶
| Setting | Description |
|---|---|
| Use LinkedIn tokens | Tick to enable LinkedIn tokens using the specified URL |
| Base URL | URL used for generating LinkedIn tokens |
Logging options¶
With the above setting, a new log is created each day.
| Setting | Description |
|---|---|
| Log Path | Path for the OrbitAPI log file |
| Main logging level | Choose Verbose, Debug, Information, Warning, Error, or Fatal. Each lower level omits the type above. |
| Microsoft logging level | As above, for Microsoft-level logging |
| System logging level | As above, for system-level logging |
| Memory usage logging enabled | Whether the amount of memory in use is written to the Orbit API log |
| Enable logging of HTTP request headers | Tick to log HTTP headers to the OrbitAPI log files. Requires at least Debug logging level. |
| Enable context detail logging | Optionally log additional data within the OrbitAPI logs (such as the data view name and user ID) |
Orbit database¶
| Setting | Description |
|---|---|
| Connection string | Connection string to the Orbit database |
| Command timeout (secs) | Command timeout |
| Connection timeout (secs) | Connection timeout |
| Enable performance logging | Tick to log database queries exceeding the performance logging threshold |
| Performance logging threshold (millis) | Threshold in milliseconds after which queries are logged |
| Test | Tests the specified connection string |
Orbit options¶
| Setting | Description |
|---|---|
| Partner Brand Name | Partner brand name to display in the UI |
| Show Brand Logo | Select to display a brand logo in the login area |
| Brand Logo | Path to an alternative brand logo (max 96px wide or tall). Can be relative to the OrbitAPI directory or an absolute URL. |
| Application Logo Dark | Path to an alternative logo at the top of the Orbit UI (170 × 40 px). Relative to the OrbitAPI directory or absolute URL. |
| Application Logo Light | Path to an alternative logo for the login page—light on dark background (170 × 40 px). Relative to the OrbitAPI directory or absolute URL. |
| Online Help URL | URL to use your own help centre |
| Privacy Policy URL | URL to use your own privacy policy |
| Partner Sales URL | If set, visible in the help icon dropdown in Orbit |
| Partner Support URL | If set, visible in the help icon dropdown in Orbit |
| Facebook Token Generation Base URL | URL used to generate OAuth tokens for Facebook (future functionality) |
| Google Token Generation Base URL | URL used to generate OAuth tokens for Google (future functionality) |
| LinkedIn Token Generation Base URL | URL used to generate OAuth tokens for LinkedIn (future functionality) |
| Twitter Token Generation Base URL | URL used to generate OAuth tokens for Twitter (future functionality) |
| Enable External Login | Select if using an SSO service provider with External Login Service configured |
| Enable Log Access Via API / UI | Controls whether administrators can download logs via the API or UI |
| Email Hyperlink Domain Allow List | Security feature: enter domains allowed within links in emails from Orbit. Recommended to match your Orbit installation URL. |
| Allow All Domains in Email Hyperlinks | Security risk—not recommended. Only available when Email Hyperlink Domain Allow List is empty. |
Note
When using an SVG logo, you must specify the width and height attributes within the SVG element. Use an aspect ratio calculator if needed. SVG files can be edited in a text editor.
Note
All logo paths are either relative to C:\inetpub\wwwroot\Orbit\assets or can be absolute URLs, for example: assets\images\brand-logo.jpg or http://www.example.com/images/my-image.svg
PeopleStage service¶
| Setting | Description |
|---|---|
| Available systems | Systems available within Orbit for campaigning |
| FastStats job timeout (secs) | Timeout for jobs using the PeopleStage service |
| Data refresh poll delay (secs) | Delay between polls to update PeopleStage data displayed |
| Populate database with PeopleStage default diagram if required | When set, if the OrbitAPI finds an empty PeopleStage database it automatically populates it with a default diagram |
Permissions service¶
| Setting | Description |
|---|---|
| Use permissions | Whether to use the permissions service in Orbit |
| Get live file state | Whether the Orbit API updates file states during a session and reflects these in the UI, rather than only on session start |
| Live file state timeout (secs) | Timeout for the file state job (if enabled) |
Process options¶
This section controls API methods useful for investigative purposes. Use under direction of Apteco.
| Setting | Description |
|---|---|
| Return API version in HTTP headers | Allow or disallow returning the API version in HTTP headers |
| Allow return process details | Allow or disallow returning details about the Orbit API's .NET process (process ID, private memory, working set, heap size, garbage collection status) |
| Allow force garbage collection | Allow or disallow manual triggering of .NET garbage collection |
Rate limiting options¶
Rate limiting is a security feature that helps prevent DDoS, credential stuffing, and brute force attacks.
| Setting | Description |
|---|---|
| Enabled | Tick to enable rate limiting |
| Password reset limit | Number of password reset requests allowed within the configured reset period |
| Password reset period | Number of periods for password reset rate limiting |
| Password reset period type | Period type: seconds, minutes, hours, or days |
| User registration limit | Number of user registration requests permitted within the configured registration period |
| User registration period | Number of periods for user registration rate limiting |
| User registration period type | Period type: seconds, minutes, hours, or days |
Session service¶
| Setting | Description |
|---|---|
| Generic responses for failed login | Whether to provide feedback on whether the username or password was incorrect. Should match the FastStats Web Service setting. |
| Use Windows authentication | Do not use—Windows Authentication is not available in Orbit. This option will be removed in a future version. |
| Use case sensitive usernames | Whether to enforce case-sensitive usernames. Should match the FastStats Web Service setting. |
| Encryption password | Setting an encryption password stores personal information encrypted in the user database. Should match the FastStats Web Service setting. |
| Hash passwords | Whether to store passwords in encrypted form. Should match the FastStats Web Service setting. |
| Hashing algorithm | Hashing algorithm to use if hash passwords is ticked. Should match the FastStats Web Service setting. |
| Use password salt | Whether to use salt in encryption. Protective against brute force attacks. Should match the FastStats Web Service setting. |
| Password expiry (days) | Password expiry time. Should match the FastStats Web Service setting. |
| Password expiry warning (days) | Password expiry warning time. Should match the FastStats Web Service setting. |
| Session expiry time (secs) | Seconds before a user's session is forcibly expired, regardless of activity. Should match the FastStats Web Service setting. |
| Session inactivity time (secs) | Seconds before a session expires due to inactivity. Should match the FastStats Web Service setting. |
| Allow simple login method using email address | Whether the API accepts email addresses as well as usernames for login credentials |
| Session validation check timeout (secs) | Timeout when validating a session. If no response is received within this timeout, the session is deemed invalid. |
| Allow auto-registration for unknown SSO users | Whether to allow unknown users connecting via SSO to be auto-registered |
| Allow return details for all valid sessions | Tick to allow details of valid sessions to be returned via the OrbitAPI |
Telemetry service¶
| Setting | Description |
|---|---|
| Disable Telemetry | Tick to disable telemetry for this data view |
| Force Opt In to Telemetry | Tick to automatically opt users into telemetry |
| Telemetry API URL | URL of the Telemetry API |
TemporaryFile service¶
| Setting | Description |
|---|---|
| Temporary file base directory path | Physical path for storing temporary files created by the API. For multi-web-server setups using the TemporaryFiles strategy in the FastStatsFile Service, set this to a UNC path accessible from all web servers. |
| Temporary file expiry time (seconds) | Expiry time for temporary files. Setting 0 means files never expire. |
TwitterTokens service¶
| Setting | Description |
|---|---|
| Use Twitter tokens | Tick to enable Twitter tokens using the specified URL |
| Base URL | URL used for generating Twitter tokens |
User service¶
| Setting | Description |
|---|---|
| Allow user self-registration | Whether to allow users to self-register in this data view |
| User registration requests expire after (mins) | Time after which user registration links expire |
| Allow users to reset their passwords | Whether to allow users to reset their passwords |
| Password reset requests expire after (mins) | Time that password reset requests remain valid |
| Minimum password length | Minimum password length. Should match the FastStats Web Service setting. |
| Minimum number of digits in password | Minimum digits required. Should match the FastStats Web Service setting. |
| Minimum number of letters in password | Minimum letters required. Should match the FastStats Web Service setting. |
| Minimum number of lowercase letters in password | Minimum lowercase letters required. Should match the FastStats Web Service setting. |
| Minimum number of uppercase letters in password | Minimum uppercase letters required. Should match the FastStats Web Service setting. |
| Minimum number of symbol characters in password | Minimum symbol characters required. Should match the FastStats Web Service setting. |
| Default group name for self-registered users | Default group for self-registering users |
| Allow registering/sharing to any email domain | Whether to allow unrestricted sharing of Orbit items |
| Restricted email domains | Space-delimited list of email domains that sharing is restricted to |
| Return full user summary details for all users | Tick to return user summary information for all users, not just administrators |
Visualisation service¶
| Setting | Description |
|---|---|
| FastStats job timeout (secs) | Timeout for jobs using the visualisation service |