Administrative Commands

Birst provides a set of administrative commands for common activities related to provisioning users and groups, managing spaces, and more. All commands are available to Account Administrators. A subset of commands are available to Space Administrators.

Execute commands from either:

Tips: 

  • If you do not have permission to execute a command, you see the message "Invalid command".
  • When you use the Command Window Help, you see only those commands for which you have permission to execute.

Web Services

Unless otherwise stated, the administrative commands are also exposed through web services. See Web Services.

Syntax

Pipes (|) signify that you pick one from multiple alternatives.

Italics signify arguments to be replaced by the actual values.

Items enclosed in braces {} are optional. Do not include the braces when specifying the optional arguments.

Arguments with spaces should be enclosed with double quotes. For example, "test space". Note: The user interface does not allow for double quotes. Double quotes can be used in the command line prompt but results in an error in the user interface.

Do not put spaces around equal signs (=).

Put a space between parameters.

Commands for Space Administrators

The following commands are available to Space Administrators and Account Administrators.

Space Operations Commands

Group and ACL Commands

Usage Tracking Commands

Data Sampling Commands

Miscellaneous Commands

User Operations CommandsUser Operations Commands

Report Catalog

Product Operations Commands

Proxy User Commands

OpenID and OpenID Connect Commands

IP Address Restriction Commands

Email Domain Whitelisting

Password Policy Commands

Salesforce.com Account Mappings Commands

Authentication Type Commands

Commands for Operations Users

Alphabetical List of Commands

These commands are available:

addacltogroup

Assigns the access control list (ACL) to the group.

addacltogroup space_name group_name acl_tag

Example:

addacltogroup Northwind USER$ ExploreInVisualizer

See Group ACLs for a list of ACL tags. Use listgroups to see a list of groups in the space. Use listgroupacls to see existing ACLs for a group in a space.

Tip: The USER$ system group contains all users who have access to the specified space.

The equivalent web service is called addAclToGroupInSpace.

addallowedip

Adds an IPv4 address or a netblock in CIDR format for a single user.

addallowedip username ip/cidr

Example:

addallowedip user1@company.com 123.234.232.0/24

Use listallowedips to see existing IPs.

For Account Administrators only.

addCloudConnection

Add cloud connection. Arguments are Login token, space id, and cloud connection.

adddomains

Specifies a comma-separated list of domains that will be honored when sending emails (whitelisting). Any other domains will not be allowed. If no domains are in this list, then an email can be sent to any domain.

Example:

adddomains birst.com,salesforce.com

Use listdomains to see existing allowed domains. Use removedomains to empty the list and allow all domains.

For Account Administrators only.

The equivalent web service is called addEmailDomains.

addipaddrforaccount

Add an IPv4 address and a netblock in CIDR format for an account.

addipaddrforaccount ip/cidr

Example:

addipaddrforaccount 123.234.232.0/24

Use listipaddrsforaccount to see existing IPs and CIDRs.

For Account Administrators only.

The equivalent web service is called AddAllowedIPAddrForAccount.

addopenid

Adds an OpenID for a user.

addopenid username open_ID

Example:

addopenid user1@myco.com, user1.myopenid.com

For Account Administrators only.

addopenidconnect

Adds an OpenID Connect ID for a user.

addopenidconnect username open_ID

For Account Administrators only.

There is no web service for this command.

addproduct

Add a Birst product for a user. Allows the user to have access to the product.

addproduct username product_ID {quantity}

Example:

addproduct pinky@acmelabs.com 2

Use listproducts to get the list of products and their product ID.

For Account Administrators only.

The comparable web service is called addProductToUser.

addproxyuser

Adds a user that you have created as a proxy for another user, with an expiration date (yyyy-mm-dd). You cannot create a proxy user for a user created by another Account Administrator.

Tip: Use the listcreatedusers command to find out who you can add as a proxy user.

addproxyuser username proxy_username expiration_date

The following example allows user1@company.com to proxy as user2@company.com:

addproxyuser user1@myco.com user2@myco.com 2016-06-31

See Proxy User Login for instructions on how to log in as the proxy user.

For Account Administrators only.

addsfdcaccountmapping

Maps a Salesforce.com account to a Birst account.

addsfdcaccountmapping salesforce_OrgID

Example:

addsfdcaccountmapping 00D...c59

Use getsfdcacountmapping to see existing mappings. Use removesfdcaccountmapping to delete a mapping.

For Account Administrators only. See Adding a Tab in Salesforce.

addusertogroup

Adds a user to a group.

addusertogroup username space_name group_name

Example results:

Executing command: addusertogroup brain@acmelabs.com Northwind "World Domination Group"
User added to group: brain@acmelabs.com, World Domination Group, Northwind

The equivalent web service is addUsertoGroupInSpace.

See Creating Groups and Adding Users to Groups.

addusertospace

Gives a user access to a space with the specified rights. To alter the rights, re-add users to the same space.

addusertospace username space_name|space_ID admin=true|false

Example results:

Executing command: addusertospace brain@acmelabs.com Northwind admin=false
User added to space: brain@acmelabs.com, Northwind, with permissions:

See Adding a User to a Space.

applysample

Apply sampling for a given level to a source. See About Data Sampling.

applysample dimension level source

checkconnections

Gets the status for all connections of a space. Status is either Active or Inactive.

checkconnections

Example results:

Executing command: checkconnections
Default Connection, Active

There is no web service for this command.

clearcache

Clears both the query and dashboard caches for a space at once. By default it clears the current space. Optionally you can specify another space.

clearcache {spaceID|space_name}

Example:

clearcache "Acme Labs Space"

See Clearing Query and Dashboard Caches. Alternatively, you can use the clearCacheInSpace and clearDashboardCache web services. See SOAP Web Services.

copyAccountSettings

The copyAccountSettings (command/API) was introduced with the 5.30 release. The purpose of this command API is to facilitate the copying of account level settings from one account to another. Note: For operations users only.

The general structure of the copyAccountSettings command is:

copyAccountSettings accountFromIDaccountToID copy options

The current options include:

  • color-palettes: Copy any consistent color palettes defined in the account.
  • themes: Copy the theme that is selected for the account.

Note: If no option is provided, then both themes and color-palettes are copied across accounts.

copyspace

The copyspace command supports copying at a granular level. The command can be executed at the command line, in a Birst Connect command file, and through web services. To copy a space from a button on the Homepage see Copying a Space. Note: When the copyspace command is used on a space, that space is locked until the process is completed.

The general structure of the copyspace command is:

copyspace from_SpaceID to_SpaceID copy|replicate options

Note: When no options are specified, Birst defaults to the following options: repository, datastore, catalog. You can also use space names in the above syntax, but names that have space should be enclosed with double quotations. (i.e. , "My Space Name") in the command line prompt.

Caution: The application displays an error message when you use double quotes and other illegal characters in the user interface. Double quotes can be used in the command line prompt but are not accepted in the user interface.

Note: If you copy objects that rely on permissions from a space group, you must copy the space group first. If you do not copy the space group first, the objects which are tied to permissions from that space group are not set up correctly.

Mode is either:

  • copy: Items in the from_SpaceID are copied over to the to_SpaceID. This is an additive action and will not remove or overwrite existing information.
  • replicate: Makes the items in the to_SpaceID the same as in the from_SpaceID. Replicate removes and overwrites information as necessary.

Mode is case-sensitive and "copy" and "replicate" should always be lowercase.

Options is a semicolon (;) separated list of items to copy/replicate between spaces. Options are case-sensitive. Note: There cannot be a semicolon at the end of the list of options. The user interface does not allow for double quotes. Double quotes can be used in the command line prompt but results in an error if used in the user interface.

Options are:

  • birst-connect [:item1; item2;...,itemN]: copy/replicate the Birst Connect (dcconfig settings). DCconfig files correspond to the configurations defined with the Admin' module Birst Connect tab. If items are specified, just copy over the specific configurations (“default” is the name of the default dcconfig file). Important: This is used for copying Birst Connect 1 configurations that you defined on the Admin Birst Connect page only. It does not include Cloud Connectors.
  • catalog[:"item1,item2,...,itemN"]: Copy/replicate the catalog. If items are specified, just copy/replicate the specific directories and files. If no items are specified, only shared and private are copied or replicated.
    For Designer report names, use the suffix .AdhocReport. For Visualizer report names, use the suffix .viz.dashlet.
    If there are spaces in the path, you need to enclose the path in double quotes.
    You can use the suffix '.page.' to copy one particular dashboard at a time.

  • catalog:DB2Bookmarks: Copy/replicate the Dashboards 2.0bookmarks.

    Note: Dashboard 2.0 bookmarks are copied along with the entire catalog if you are using the 'catalog' option by itself. This option is lets you copy only the Dashboard 2.0 bookmarks. Use DB2Bookmarks in place of a directory or file name, such as "catalog:DB2Bookmarks". To copy the bookmarks along with other related catalog files, include the DB2Bookmarks as another option in the comma-separated list of options.

  • connectors: This parameter will copy/replicate connector configurations. This includes a large file upload, RDBMS, Cloud Connectors, Live Access connections, REST connectors etc.
    To copy connector configurations:
    copyspace from_SpaceID to_SpaceID copy connectors

  • color-palettes: Copy/replicate any consistent color palettes defined in the space.
    copyspace from_SpaceID to_spaceID copy|replicate color-palettes

    Important: If a palette is copied to another account where palettes with the same already exist, "_migration" is added to the end of the copied over palettes to avoid duplicates.

  • customGeoMaps.xml: Copy/replicate any custom Geo Maps for the space.

  • custom-groups: Copy/replicate Custom Groups
    copyspace from_SpaceID to_spaceID copy|replicate attribute-groups;SavedExpressions.xml

  • custom-subject-areas[:item1; item2;...itemN]: Copy/replicate the custom subject areas. The permissions tied to the custom subjects areas are also copied. If items are specified, just copy over the specific custom subject area(s). (“default” is the name of the default custom subject area).

  • custom-subject-areas-no-permissions[:item1; item2;,...itemN]: Copy the custom subject areas without the permissions tied to them. You must explicitly list the subject areas, for example:
    custom-subject-areas-no-permissions:csa1,csa2

  • dashboardstyles: Copy/replicate the dashboard style settings.

  • data: Copy/replicate raw data files.

  • datastore: Copy/replicate the entire datastore. Note that this option does not copy/replicate the raw data files, only the database tables and indices.
    The datastore option includes all of the options beginning with "datastore-" listed below. If only part of the datastore needs to be copied, the options listed below can be used in place of datastore to copy the group of items indicated.

    • datastore-warehouse: Copy/replicate the data warehouse tables (i.e. – DW*) and indices.

    • datastore-warehouse_tables: Copy/replicate the data warehouse tables.

    • datastore-warehouse_indices: Copy/replicate the data warehouse indices.

    • datastore-staging: Copy/replicate the data warehouse staging tables (i.e. – ST*) and indices.

    • datastore-staging_tables: Copy/replicate the data warehouse staging tables.

    • datastore-staging_indices: Copy/replicate the data warehouse staging indices.

    • datastore-aggregates: Copy/replicate aggregates.

    Note: You cannot copy the datastore or the repository when the from datawarehouse is different from the to datawarehouse.

  • DrillMaps.xml: Copy/replicate drill maps.
  • global-filters: Copy/replicate global filters.
    copyspace from_SpaceID to_spaceID copy|replicate global-filters
  • networks: Copy/replicates Networks including the information about user groups who have access to the package
    copyspace from_SpaceIDto_SpaceID copy|replicate networks:network_name1,network_name3
  • networks-no-permissions: Copy/replicates Networks without permissions.
    copyspace from_SpaceID to_SpaceID copy|replicate networks-no-permissions:network_name1,network_name3

  • packages: Replicates or copies either all packages or specified packages, including the information about user groups who have access to the package. With copy mode, Birst copies the packages and no existing packages are removed in the to_SpaceID. With replicate mode, Birst copies the packages and removes the packages in to_SpaceID that do not exist in from_SpaceID.

    Important: The packages option always uses replicate mode for elements in each package.

    copyspace from_SpaceID to_SpaceID copy|replicate packages

    copyspace from_SpaceID to_SpaceID copy|replicate packages:package_name1,package_name3

    Important: When you copy a child space and its packages, the packages in the child space will, by default, point to original parent space that the packages originated from. For more details on how to change where copied packages point, see repointPackages.

  • packages-no-permissions: Same as packages, but does not replicate the relationships between packages and user groups. After running this command option, there won't be any user groups listed for the package in Admin - Customize Space - Packages- Modify- Access tab.

  • repository: Replicates the repository.xml, repository_dev.xml, and packages.xml. Birst rebuilds the repository and saves it such that its database connection information is correct.
    Important: The repository option always uses replicate mode, even if you use copy mode in the syntax. The destination repository becomes exactly like the source repository and any sources that exist only in the target space are deleted.
    • repository:no-security-filter Replicates the repository.xml, repository_dev.xml, and packages.xml without security filters. copyspace from_SpaceID to_SpaceID copy|replicate repository:no-security-filters
      • The repository:no-security-filtercommand can be used with the security-filters command to only copy over specified filters. Security filters are named after the hierarchy and attribute name they're set to secure in the following syntax HierarchyName.AttributeName. For example, if you have set up a security filter on the [Products.CategoryID] attribute the security filter should be Products.CategoryID.
        copyspace from_SpaceID to_SpaceID copy|replicate repository:no-security-filters security-filters:HierarchyName.AttributeName

  • SavedExpressions.xml: Copy/replicate saved expressions.

  • schedules-report: Copy/replicate all report schedules or specified report schedules.
    copyspace from_SpaceID to_spaceID copy|replicate schedules-report{:schedule1_name, schedule2_name, ...}
  • spacesettings.xml: Copy/replicate custom logo/header color information.
  • security-filters: Copy/replicates security filters. Security filters are named after the hierarchy and attribute name they're set to secure in the following syntax HierarchyName.AttributeName. For example, if you have set up a security filter on the [Products.CategoryID] attribute the security filter should be Products.CategoryID.
    copyspace from_SpaceIDto_spaceID copy|replicate security-filters:HierarchyName.AttributeName,Products.CategoryID
  • settings-basic: Copy/replicate the load number. This parameter also carries over the following information to the target space: mode (advanced, automatic, or discovery), processing engine version, Salesforce loader version, query language version.

    The load number on a space is only copied if data warehouse tables are also copied, such that the copyspace options contain either of “datastore”, “datastore-warehouse_tables”, “datastore-warehouse”.

    Load number is incremented after the next successful processing run. If the datastore/datawarehouse tables are not copied, then the load number should remain untouched.
  • settings-permissions: Copy/replicate the groups and ACLs, including group membership. Note that this does not copy over space membership.
  • settings-membership: Copy/replicate space memberships for users.
  • smart-config: Copy/replicate the space's SMART configurations.
    copyspace from_SpaceIDto_spaceID copy|replicate smart-config
  • stories: Copy/replicate stories.
    copyspace from_SpaceID to_spaceID copy|replicate stories
  • tags: Copy/replicate Report Catalog tags.
    copyspace from_SpaceIDto_spaceID copy|replicate tags
    Important: This command copies/replicates the tags for assets that share the same path on both the source and target space. If you have assets in the source space that are not present in target space, the tags will not copy to the target space. If you would like to copy all items in Report Catalog and their associated tags, use the command catalog;tags.
  • translation: Copy/replicate translation.
    copyspace from_SpaceID to_spaceID copy|replicate translations
  • themes: Replicates the theme that is selected for the space.
    copyspace from_SpaceID to_SpaceID replicate themes
    Important: This is a replicate operation, regardless of whether you accidentally use the copy flag. If the target space has a non-default theme applied to it and the copied space does not, the theme in the target will be removed and the default theme will be applied.

Examples of the Copyspace Command

To update the catalog in to_SpaceID so it matches the catalog in from_SpaceID:

copyspace from_SpaceID to_SpaceID replicate catalog

To replicate the custom subject areas "csa1" and "csa2" from one space to another:

copyspace from_SpaceID to_SpaceID replicate custom-subject-areas:csa1,csa2

To replicate the Birst Connect dcconfig settings, replicate the shared/reports catalog directory, copy private/user1@birst.com/rpt.AdhocReport, and replicate the dashboard styles:

copyspace from_SpaceID to_SpaceID replicate birst-connect;catalog:shared/reports,private/user1@birst.com/rpt.AdhocReport;dashboardstyles

To copy the database and the repository from one space to another space:

copyspace from_SpaceID to_SpaceID copy datastore;repository

For Dashboards 2.0, to copy the dashboard collection folder, including the dashboards, reports, and associated filters stored in that folder, from one space to another.

copyspace from_SpaceID to_SpaceID copy catalog:shared/collection_folder_name

copyWorkflow

Lets an Operations User copy a workflow from one account to another account. Note: This operation is limited to one workflow at a time.

The arguments are the Login token, the source account ID, the workflow ID to copy from, the target account ID, the owner ID of the new workflow in target account, the space ID mapping for workflow task parameters, the user ID mapping for workflow task parameters.

Note: For operations user only.

createaudittable

Creates an audit log table. The audit log database must already exist.

createaudittable

For Account Administrators only.

Not available as a web service.

creategroup

Creates a group.

creategroup space_name group_name

Example:

creategroup "Acme Labs Space" "World Domination Group"

createsample

Create a sample set for a given dimension level of a given percent using a source. See Data Sampling.

createsample dimension level source percent

createuser

Creates a new user. The only required parameter is username. It must be unique in the system and it cannot contain spaces. Infor recommends that the value of username be the same as the user's email address.

For additional information see Creating a User and Password Policy.

createuser username {email=email_address} {password=password}

Example results:

Executing command: createuser brain@acmelabs.com password=TotalW0rld email=brain@acmelabs.com
User added: brain@acmelabs.com

For Account Administrators only.

The comparable web service is adduser.

deleteBirstConnectAgent

Used to delete an existing birst connect agent. Arguments are Login token and agent ID and returns true if successful.

deleteCloudConnection

Used to delete cloud connection. Arguments are Login token, space id and connection id.

deletegroup

Deletes a group.

deletegroup space_name group_name

Example:

deletegroup "Acme Labs Space" "World Domination Group"

deletesamples

Delete all created sample files in a path. See About Data Sampling.

deletesamples

deleteuser

Deletes a user account. A user cannot be deleted if the user is the owner of a space.

deleteuser username

For Account Administrators only.

derivesample

Create a sample set for a given dimension level using another dimension level sample and a staging table as cross reference. See About Data Sampling.

derivesample source_dimension source_level target_dimension target_level Source

downloadbulkqueryresults

Once data has been uploaded using the generatebulkqueryresults command, use downloadbulkqueryresults to copy a file down to your local system. The file will arrive as a pipe delimited text file that is compressed with a .zip extension. This command retrieves one file at a time from a specific space and copies the file down to a local directory.

downloadbulkqueryresults file_name local_directory

Important: The downloadbulkqueryresults command can only be issued using a command file when running Birst Connect from the command line. Because it requires a local path where file is to be downloaded, it cannot be run using the Command Window or a command file through Birst Connect.

dropaggregate

Drop the named aggregate. The definition must already exist.

dropaggregate aggregate_name

dropuserfromgroup

Drops a user from a group.

dropuserfromgroup username space_name group_name

dropuserfromspace

Removes a user from a space.

dropuserfromspace username space_name

enableAccount

Enables/Disables an Account. Arguments are the Login token, an AccountID, and a boolean, if true enable, if false disable

Note: For Operations Users only.

enableMongoConnectorConfig

Enable Mongo Connect Config for the given space.

enablemongoconnectorconfig [spaceId]

enableuser

Enables or disables a user account.

enableuser username true|false

Example:

enableuser user1@company.com false

For Account Administrators only.

extractCloudConnectorData

Extracts data sources from any available Connection.

Arguments are Login token, space id, Connector Name, Connection Name, Extract Group list and returns an extraction token.

Tip: Use getJobStatus and isJobComplete to check the status.

generatebulkqueryresults

Generates bulk results for logical query or report. This command supplies a logical query, file name, a flag to use logical or physical query, and the max number of records to return. When the command is executed, Birst will write the results to a compressed (zip file) pipe delimited text file for that specific space. Once data has been uploaded using the GenerateBulkQueryResults command, use the downloadbulkqueryresults command to copy a file to your local system.

generatebulkqueryresults query=logical_query |reportpath=path_of__report_in_catalog filename=output_filename {numrows=maximum_number_of_rows} {uselogical=true|false}

Parameters:

query: either a logical query or the path to a saved report. Example value for query: "Select [Time.Date] From [All]" Example value for report: /shared/myRpt

filename: the file name of the pipe-delimited text file to create. If the file name already exists, it will automatically overwrite the file with the newest version.

numrows: Optionally resets the number of rows exported. The default is 250000 records. Specifying numrows overrides the default.

uselogical: Optionally determines whether to execute a physical or logical query. A physical query returns the exact columns from the database. If any of the columns are expressions then it is a logical query because that calculation is done in memory after the entire result set is brought back from the database.

This command can be issued using a command file, from the Command Window, or via the command line.

Infor allows a maximum of 10 files in the directory. Once the limit has been reached, the oldest file will be deleted as new files are uploaded.

getAgentHealth

Used to get the health status of agents. Arguments are agent IDs and returns agent status.

getauthentication

Returns the authentication setting for the account. Use setauthentication to change the setting.

getauthentication {account_ID}

Example results:

Executing command: getauthentication
Authentication settings: Birst Authentication (default)

For Account Administrators only.

There is no web service for this command.

getDatabaseLinksStatus

Returns a boolean to specify if a space requires database links to be enabled in order for queries within the space to work. For information on enabling the Database Links property, see Modify Space Properties.

getDatabaseLinksStatus spaceIdspaceId2spaceId3

getdatacharacteristics

Returns data characteristics for a given source. Arguments are SpaceID, sourcename, and data characteristics.

getdatacharacteristics spaceIdsourcename

For example:

  • getdatacharacteristics 4e0e57b7-eeef-4c11-8a61-9473ead56103 Categories

  • getdatacharacteristics 4e0e57b7-eeef-4c11-8a61-9473ead56103 "Categories New Source"

Note: If your sourcename has whitespace in its name, you must enclose the sourcename within double quotes.

You can use the getdatacharacteristics command for a source with a Tab separator. For example:

Request:

getdatacharacteristics c25cfc80-5c89-40b1-be7c-897726bd7b8a Categories_tab

Response:

Executing command: getdatacharacteristics c25cfc80-5c89-40b1-be7c-897726bd7b8a Categories_tab

Data characteristics are: onlyquoteafterseparator: False, hasheaders: True, forcenumcolumns: False, separator: TAB, ignoredfirstrows: 0, ignoredlastrows: 0, quote: ", encoding: UTF-8, donottreatcarriagereturnasnewline: False

Note: This command should only be used for sources getting extracted through a SFTP connector. Please use the Data Characteristics option in Modeler Connect for sources extracted using other connectors.

getid

Allows users to find the ID of specific objects for use in other commands.

Note: Currently, users are only allowed to run getid for to get the ID of a given connection.

Prerequisites:

  • Users need to be account administrators to perform the getid command

The specific inputs for the getid command are:

{[SpaceID|/[SpaceName]}

[objectName]

{[SpaceID|/[SpaceName]}is an optional input. If it is not provided, it is assumed that the user meant to run this command at the account level. If it is provided, only the object types for the space specified in the command is returned. Object type example: connection

[objectName] represents the name of the object for the ID that is requested.

getid example:

getid 32f85168-3223-4138-b238-1a1998b24d07 connection "Data Lake Shared Connection"

getid connection "Data Lake Shared Connection"

getlanguageforuser

Returns the language assigned to a user.

getlanguageforuser username

For Account Administrators only.

getmaxmessagesize

Returns the max size allowed for email messages.

getpasswordpolicy

Returns the password policy for the account. The accountID is required for Appliance customers. See Changing the Password Policy.

getpasswordpolicy {account_ID}

Example Results:

Executing command: getpasswordpolicy
Password Policy is: description: Passwords must be 8 characters in length and 
contain at least one number, regEx: , minLen: 8, maxLen: 0, mixedCase: False, 
special: False, numeric: True, nousername: True, changeonfirstuse: True, 
history: 0, expiration: 0, hashalgorithm: base, maxfailedloginattempts: 3, 
failedloginwindow: 20

For Account Administrators only.

getsfdcaccountmapping

Returns all Salesforce.com accounts that are mapped to a Birst account.

getsfdcaccountmapping

Use with addsfdcacountmapping and removesfdcaccountmapping.

For Account Administrators only.

getspaceid

Get the ID for a space name.

getspaceid space_name

getusage

Imports and publishes the usage information for all spaces in an account and put it into a Usage Tracking space for processing. Usage Tracking is a type of space available to Account Administrators. If the Usage Tracking spaces does not already exist, the command will create a new space. If the space does exist, the command will updated and publish the information. See Performing Usage Tracking for more information.

Note: You must use double quotes for space names. If your space name has whitespace or a space in its name, you must enclose the space name within double quotes.

By default, this command extracts the usage data. Optionally, you can specify a source to extract data from to extract usage data, space overview data, or both.

getusage usage_tracking_space_name from_date sources=usage,spaceOverview

Example:

getusage "Usage Tracking for Account" 2015-01-01

Note: The date format to use is 'fromdate' (yyyy-MM-dd) until 'todate' (yyyy-MM-dd). If you do not provide a "todate" parameter value, the current date is used to return all records to date.

getuserrelease

Gets the release for a user.

getuserrelease username

For Account Administrators only.

legacyfeatures

Turns the creation of legacy feature objects on or off for the account. When this command is run without the on/off parameter, it will return whether the account can currently create legacy feature objects or not.

legacyfeatures {on/off}

listallowedips

Lists all IPv4 addresses and netblocks from where the user can log in. Results include both user and account iPv4 and netblocks.

listallowedips username

Example:

listallowedips brain@acmelabs.com

For Account Administrators only.

listCloudConnections

List cloud connections. Arguments are Login token and spaceId. It would return list of connection.

listcreatedusers

Lists all users.

listcreatedusers

listdomains

Lists the whitelisted email domains that will be honored when sending emails. Any other domains will not be allowed. The domains in the list were previously added using either the adddomains command or the AddEmailDomains web service.

Example:

listdomains

For Account Administrators only.

Use removedomains to empty the list and allow all domains.

The equivalent web service is called listEmailDomains.

listgroupacls

Lists ACLs for a group.

listgroupacls space_name group_name

Example Results:

Executing command: listgroupacls Northwind USER$
Dashboard

listgroups

Lists groups for a space.

listgroups space_name

Example Results:

Executing command: listgroups Northwind
OWNER$
USER$
World Domination Group

listipaddrsforaccount

Lists all IPv4 addresses and netblocks from where users in the account can log in.

listipaddrsforaccount

For Account Administrators only.

listlanguages

Lists all supported languages for the account or for a specified user.

listlanguages {username}

For Account Administrators only.

listmanagedusers

Lists all users managed by the Account Administrator running the command.

listmanagedusers

For Account Administrators only.

listopenids

Lists all OpenIDs for the user.

listopenids username

For Account Administrators only.

listopenidconnects

Lists all OpenID Connect IDs for a user.

listopenidconnects username

For Account Administrators only.

Not available as a web service.

listproducts

Lists all products for the account and their product IDs, or optionally those assigned to a particular user.

listproducts {username}

Example results:

Executing command: listproducts
9, Birst Connect
10, Birst Live Access
11, Birst Web Services

Use addproduct to assign a user access to a product.

For Account Administrators only.

Not available as a web service.

listproxyusers

Lists all proxy users that were added using addproxyuser. It does not list any of the implicit proxy users, the members of your account.

listproxyusers

For Account Administrators only.

listreleases

Lists the available releases.

listreleases

For Account Administrators only.

listspacesforusage

List the spaces that will be used in the getusage command. See Performing Usage Tracking for more information.

List the spaces that have been set up for usage tracking by chercking the Allow Usage Statistics Extracts box. These are the spaces you need to run the getusage command from in order to retrieve each space's usage tracking data. See Performing Usage Tracking for more information.

listspacesforusage

listusersingroup

List users in the group.

listusersingroup space_name group_name

Example results:

Executing command: listusersingroup Northwind "World Domination Group" 
brain@acmelabs.com
pinky@acmelabs.com

Tip: Use listusersingroup space_name OWNER$ to see the owner of a space.

listusersinspace

List users in the space.

listusersinspace space_name

Example:

listusersinspace "Acme Labs Space"

migratelaconnectiontobc2

Migrates Birst Connect 1.0 Live Access connections metadata to Birst 2.0 Live Access connection. See Migrate Birst Connect 1.0 Live Access Connections Metadata to Birst Connect 2.0 for more information. 

migratelaconnectiontobc2 [spacename | spaceid] [bc1connectionname | connectionid] [agentname]

persistaggregate

Persist the named aggregate. This creates the aggregate table or tables in the data store (warehouse). The definition must already exist, as defined in Admin - Customize Space - Manage Aggregates. Use the persistaggregate command when you want to create the aggregate tables without reprocessing all of the data. When the command completes, an email is sent to the Space Owner. See Creating an Aggregate.

persistaggregate aggregate_name

Caution: If a PersistAggregate failure occurs, a space administrator must intervene to fix the problem with the PersistAggregate error. When a PersistAggregate failure occurs, the application does not mark the entire ETL process as a failure. This leads to a scenario where the aggregate cannot be used for the space, and there is no indication to users that the failure occurred. Instead, processing is shown as successful in the publishing logs but orchestration and monitoring logs show failures without any error messages.

rebuildindices

Rebuild the indices for the space schema of the current space. For Appliance customers with Birst repository databases on SQL Server 2014 only.

rebuildindices

registerBirstConnectAgent

Used to register a new Birst connect agent. Arguments are Login token, agent name and agent description and returns the unique id of the registered agent.

removeaccountoverrideparameter

Removes the override parameter for this account from the list of allowed account override parameters. If no such parameter exists, command will inform that in the result.

removeaccountoverrideparameter [parametername]

removeaclfromgroup

Remove the ACL from the group.

removeaclfromgroup space_name group_name acl_tag

See Group ACLs for a list of ACL tags.

removeallowedip

Remove an IPv4 address or a netblock in CIDR format.

removeallowedip username ip/cidr

For Account Administrators only.

removedomains

Removes all whitelisted domains. After running this command, an email can be sent to any domain. Use adddomains to repopulate the list.

Example:

removedomains

Use listdomains to see existing allowed domains.

For Account Administrators only.

The equivalent web service is called removeEmailDomains.

removeipaddrforaccount

Remove an IPv4 address or a netblock in CIDR format.

removeipaddrforaccount ip/cidr

Example:

removeipaddrforaccount 123.234.232.0/24

For Account Administrators only.

removeopenid

Removes an OpenID from a user.

removeopenid username open_ID

For Account Administrators only.

removeopenidconnect

Removes an OpenID Connect ID from a user.

removeopenidconnect username open_ID

For Account Administrators only.

There is no web service for this command.

removeproduct

Remove a product from a user.

removeproduct username product_ID

Use listproducts to see the products assigned to a user and the product ID.

For Account Administrators only.

The web service is called RemoveProductFromUser.

removeproxyuser

Drops a user as a proxy for another.

removeproxyuser username proxy_username

For Account Administrators only.

removesample

Remove sampling for a given level from a source. See About Data Sampling.

removesample dimension level source

removesfdcaccountmapping

Removes the mapping of a Salesforce.com account to a Birst account.

removesfdcaccountmapping salesforce_OrgID

Use getsfdcaccountmapping to see a list of existing mappings.

For Account Administrators only.

repointConnections

The repointconnection command allows sources in a space to be repointed to a different shared connection.

repointConnections Space_1 SMD_Connection Connection

One use case is when a space is copied into another Birst account that does not have access to the original shared connection. This is because shared connections are only accessible within the account in which they are created. In this situation, the sources are inaccessible until the connection is repointed to a valid shared connection in the Birst account.

Note Currently, users are only able to repoint shared connections (e.g created at the account level, accessible across spaces). “Standard connections” (e.g. connections created within a space) cannot be repointed.

Prerequisites:

  • Users need to be an space administrator to perform the repointconnection command.

  • The space for which the user is running the command needs to belong to the account that the user is an administrator of.

  • The new shared connection that the user wants to repoint the connection to needs to belong to the account that the user is an administrator of.

The specific inputs for the repointconnection command are:

[spaceId] [fromConnectionId] [toConnectionId]

Where spaceId is a specific customer space id, fromConnectionId is the id of the original connection that was used for the shared connection, and toConnectionId is the shared connection id for that the user wishes to repoint the connection to. For example: 

repointconnection 48d55c60-0237-47fc-b655-a78251759097 72457947373214185445798787380818

Related commands:

  • getid connection "[shared connection name]"

  • Note This command needs to run in the space/account where each shared connection was created. See the getid command.

  • getspaceid "[space name]"

  • Note The user must be a space admin of this space.

repointPackages

Arguments are the Login token, childSpace Id, oldParentSpace Id, newParentSpace Id

Note: As of 7.7., the oldParentSpace Id supports Read Only spaces.

Important: When you copy a child space and its packages, the packages in the child space will, by default, point to original parent space that the packages originated from. If you want the packages in the new copied child space to point to a copy of the parent space, (i.e. a copy of the original space from which the packages originated), you will need to employ the repointPackages web service to change where the packages in the copied child space point. This API lets you change the parentID of the imported package in the newly copied child space. See the Birst Command Web Service library for more details.

repointnetworks

Repoints the imported networks in child space from existing parent space to new parent space.

Important: When you copy a child space and its networks, the networks in the child space will, by default, point to original parent space that the networks originated from. If you want the networks in the new copied child space to point to a copy of the parent space, (i.e. a copy of the original space from which the networks originated), you will need to employ the repointNetworks web service to change where the networks in the copied child space point. This API lets you change the parentID of the imported network in the newly copied child space. See the Birst Command Web Service library for more details.

repointnetworks [childspaceid] [existingparentspaceid] [newparentspaceid]

resynchronizefiles

Synchronizes file system between the old report catalog and the HTML5 version of report catalog.

resynchronizefiles {{spaceId|spaceName}

setaccountoverrideparameter

Sets the value for allowed account override parameter for the current logged in account admin user's account. Existing values will be replaced. For example, setting the parameter DISABLE_USER_SEARCH_IN_SPACE to true disables autocomplete for searches.

setaccountoverrideparameter [parameter name] [parameter value]

setAgentsToConnectionMapping

Used to map agents to Connections. Arguments are Login token, and connection to agent mappings.

setauthentication

Sets the authentication type for the account. The type is BIRST. Use getauthentication to see the current setting.

setauthentication BIRST {host_name} {secret}

Examples:

setauthentication BIRST

For Account Administrators only.

There is no web service for this command.

setdatacharacteristics

Sets data characteristics for given source. Arguments are SpaceID, sourcename, and data characteristics.

setdatacharacteristics [SpaceID] [sourcename] {onlyquoteafterseparator=[true|false]} {donottreatcarriagereturnasnewline=[true|false]} {hasheaders=[true|false]} {forcenumcolumns=[true|false]} {separator=[char]} {ignoredfirstrows=[number]} {ignoredlastrows=[number]} {quote=[char]} {encoding=[string]}

Note: If your sourcename has whitespace in its name, you must enclose the sourcename within double quotes.

The table below shows the data characteristics and their possible values:

Data Characteristics Name

Accepted Values
onlyquoteafterseparator

true

false
donottreatcarriagereturnasnewline

true

false
hasheaders

true

false
forcenumcolumns

true

false
separator

,
|
:
:
-
Custom Separator
ignoredfirstrows Any natural number, numeric value
ignoredlastrows Any natural number, numeric value
quote

"
'
Custom Quote Character
encoding UTF-8
"UTF-16(Little Endian)"
"UTF-16(Big Endian)"
EUC-KR

Note: You must enclose UTF-16(Little Endian) and UTF-16(Big Endian) within double quotes because the name contains whitespace.

You can set a Tab separator using the setdatacharacteristics command. For example:

Request:

setdatacharacteristics c25cfc80-5c89-40b1-be7c-897726bd7b8a Categories_tab separator=TAB

Response:

Executing command: setdatacharacteristics c25cfc80-5c89-40b1-be7c-897726bd7b8a Categories_tab separator=TAB

Setting data characteristics on Source 'Categories_tab' for Space c25cfc80-5c89-40b1-be7c-897726bd7b8a

Setting data characteristics on Source 'Categories_tab' for Space c25cfc80-5c89-40b1-be7c-897726bd7b8a completed.

Note: This command should only be used for sources getting extracted through a SFTP connector. Please use the Data Characteristics option in Modeler Connect for sources extracted using other connectors.

setdenycreatespace

Prevents a user from creating a new space.

setdenycreatespace username true|false

For Account Administrators only.

There is no web service for this command.

setlanguageforuser

Sets a supported language for a user. Use the listlanguages command to see the list of supported languages with their language codes.

setlanguageforuser username language_code

Example:

setlanguageforuser user1@birst.com en-us

For Account Administrators only.

setmaxmessagesize

Defines the max size allowed for email messages in bytes.

setmaxmessagesize limit

Example:

setmaxmessagesize 1000

This sets the max email message size to 1000 bytes.

setpasswordpolicy

Sets the password policy for the account. The accountID is required for Appliance installations. Each time you run setpasswordpolicy it fully replaces the pre-existing policy.

By default, the minimum requirements for passwords include: all passwords must be a minimum of 6 characters in length, cannot be the username, and cannot contain sequences or repeated characters or be commonly-used passwords. For the complete definition see Password Policy.

For Account Administrators only.

setpasswordpolicy "policy_options" "description" "{regular_expression}" {accountID}

Parameters

Policy_options is a comma-separated list of key-value pairs, enclosed in double quotes. There are no spaces between the pairs and commas. Keys are:

minlength - Minimum password length. Cannot be set to less than 6.

maxlength - Maximum password length.

containsmixedcase - true/false; Must contain both upper and lower case characters.

containsspecial - true/false; Must contain at least one special character.

containsnumeric - true/false; Must contain at least one numeric character.

doesnotcontainusername - true/false. Must not contain the user name string.

historylength - Number of passwords that cannot be repeated.

expirationdays - Number of days until password expires. The expiration time is determined by the delta of the time when a user logs in and the time of the user's last password change. The last password change date for a new user is the date when the user was created.

changeonfirstuse - true/false; Force user to change password on first login. This is useful for ensuring that user passwords are private.

maxfailedloginattempts - Maximum number of failed login attempts allowed before user is locked out (defaults to 5).

failedloginwindow - Time in minutes before a user account is unlocked after the maxfailedloginattempts has been reached (defaults to 10 minutes).

hashalgorithm - Refer to NIST SP 800-132 for information about password hashing algorithms.

pbkdf2:prf:iterations
-pbkdf2 stands for Password-based Key Derivation Function.
- prf (Pseudo Random Function) is one of the following: hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512
- iterations should be between 1000 and 100000.

description is a text field enclosed in double quotes. Describe your new policy here.

regular_expression optionally allows you to require a specific character. For example, a regular expression could require all passwords to start with a number: ^[0-9]. For another example, to require at least one lower case character: [a-z]+. Otherwise, leave it blank, but enter the double quotes.

accountID is required for Appliance accounts. It does not require double quotes.

Example

setpasswordpolicy "minlength=8,containsnumeric=true,historylength=5,expirationdays=30,changeonfirstuse=true,maxfailedloginattempts=3,failedloginwindow=20,hashalgorithm=pbkdf2:hmac-sha256:50000" "Passwords must be 8 characters in length and contain at least one number" ""

See Changing the Password Policy.

setspacessopassword

Set the space SSO password.

setspacessopassword spaceID password

setuserdefaultspace

Sets the default space for a user and sets if they default to dashboards (true/false).

setuserdefaultspace username spaceID true|false

Example:

setuserdefaultspace user1@company.com 5bf1dff7-1f47-4dc6-a16b-d8529b76e37b true

For Account Administrators only.

Tip: Users can set their own default space from their User Settings. See Changing the Default Start Page and Space.

setuserpassword

Sets the password for a user.

setuserpassword username password

Example:

setuserpassword user1@company.com h4h4h4N4rf!

For Account Administrators only.

setuserrelease

Sets the release for a user.

setuserrelease username release

Example:

setuserrelease pinky@birst.com 5.22

For Account Administrators only.

setuserrendertype

Sets the Original Dashboards module to HTML5 or Flash, or set Dashboards 2.0, for a user. The default for existing users is Flash.

setuserrendertype username html|flash|dashboard2.0

Example:

setuserrendertype pinky@birst.com dashboard2.0

For Account Administrators only.

There is no comparable web service for this command.

setvariable

Sets the value of a variable.

setvariable variable_name value

showsamples

Show all samples present in a path. See About Data Sampling.

showsamples

swapspacecontents

This command swaps the data and catalog of two different spaces while keeping users and implementation-specific elements like report schedules the same. It is the same as the Admin - Manage Spaces - Modify Properties - Swap Content With Another Space option.

A common use of this feature is to swap the contents of a development space with a production one. See Distributed Development Model.

For spaces using Managed Data Mashups, use swapspaceforpackages.

Swapspacecontents does not swap the following:

  • Users and groups
  • Group permissions and memberships
  • Data processing schedules
  • Report schedules
  • SSO settings

swapspacecontents space1_name space2_name

Example:

swapspacecontents "Test Space" "Production Space"

swapspaceforpackages

Swaps the content of space 1 with that of space 2, and allows syncing of imported packages. Use swapspaceforpackages when you want to swap Managed Data Mashup spaces that contain packages.

swapspaceforpackages prod=space1_name dev=space2_name syncImportedPackages=true|false

Example:

swapspaceforpackages prod="Production Space" dev="Test Space" syncImportedPackages=true

testpassword

Test a password against the account password policy. The accountID is required for Appliance customers.

testpassword password username {accountID}

Example:

testpassword s3kr1T user1@company.com

For Account Administrators only.

unlockuser

Unlocks a user.

unlockuser username

Example:

unlockuser user1@company.com

For Account Administrators only.

updateBirstConnectAgent

Used to update an existing Birst connect agent. Arguments are Login token, agent ID, new agent name and new agent description and returns true if successful.

updateAsyncExtractionStatus

Enables or disables Async Extraction for a given space.

updateasyncextractionstatus [spaceId] [enable:true|false]

updateAsyncProcessingStatus

Enables or disables Async Processing for a given space.

updateasyncprocessingstatus [spaceId] [enable:true|false]

updateCachedRepositoryStatus

Enables or disables Cached Repository for the given space.

updatecachedrepositorystatus [spaceId] [enable:true|false]

updateCloudConnection

Used to update cloud connection. Arguments are Login token, space id, connection id and cloud connection.

updatestats

Update query optimization statistics on tables and/or index views of the space. For SQL Server only.

updatestats

Not available as a web service.

upgradeAgent

Used to upgrade an existing Birst connect agent. Arguments are Login token and agent IDs and returns true if successful.

validatemetadata

Run rules against the repository to validate the metadata. This command is not available as a web service. For more information, see Validating Your Data Model.

validatemetadata all

validatemetadata rule ruleName

validatemetadata rulegroup ruleGroupName

Examples:

validatemetadata rule IncrementalSnapshotFact

validatemetadata rulegroup "Data Sources"

See Also: