Space operations commands

addusertospace

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

addusertospace usernamespace_name|space_ID admin=true|false

Example results:

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

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"

Alternatively, you can use the clearCacheInSpace and clearDashboardCache web services.

clearspacestatus

Caution: 
This command should only be used when a space operation is stuck or unresponsive.

Clears the status of a selected space or space ID. This command clears the status for the selected space and sets it to Available. 

clearspacestatus
Note: Space administrators and space owners can use this command.

clearconnectorstatus

Clears the connector status of a selected space or space ID. This command clears the status for the selected space and sets it to Available to start the connector extraction job or any other job again. 

clearconnectorstatus
Caution: 
You should only use this command to clear the connector status if the connector extraction seems to stall or hang.
Note: Space administrators and space owners can use this command.

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.
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_SpaceIDto_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.

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).
    Caution: 
    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.
    • If a report catalog needs to be copied and nested in a folder, then the destination space should also have the same folder structure present in it. So either you can create the missing folder in destination space and then run the command:
      Copyspace 12a34b56-7a89-10c2-345-a123dbf4dc56 01abcv2c-abc3-4f5c-6f7b copy catalog:"shared/Subscriptions/ABC/documentation.viz.dashlet"

      Or run a command like this:

      Copyspace 12a34b56-7a89-10c2-345-a123dbf4dc56 01abcv2c-abc3-4f5c-6f7b copy catalog:"shared/Subscriptions/ABC"

      In this example, everything present in the ABC folder will be copied to the destination.

  • catalog:DB2Bookmarks: Copy/replicate the Dashboard bookmarks.
    Note: Dashboard 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 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.
  • conditions: This parameter copies/replicates data driven dashboard conditions. To copy data driven dashboard conditions:copyspace from_SpaceID to_SpaceID copy conditions
  • 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_SpaceIDto_spaceID copy|replicate color-palettes
  • customGeoMaps.xml: Copy/replicate any custom Geo Maps for the space.
  • custom-groups: Copy/replicate Custom Groupscopyspace from_SpaceIDto_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: 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.
    Note: For copyspace operations with datastore option from non Always ON spaces to Always ON spaces, disable the Always ON option on the Target space before the copyspace operation. After the operation is completed, enable the Always ON on the Target space.
    • 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_SpaceIDto_spaceID copy|replicate global-filters
  • networks: Copy/replicates Networks including the information about user groups who have access to the packagecopyspace from_SpaceIDto_SpaceID copy|replicate networks:network_name1,network_name3
  • networks-no-permissions: Copy/replicates Networks without permissions.copyspace from_SpaceIDto_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.
    Caution: 
    • The packages option always uses replicate mode for elements in each package.copyspace from_SpaceID to_SpaceID copy|replicate packagescopyspace from_SpaceIDto_SpaceID copy|replicate packages:package_name1,package_name3.
    • 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.
    Caution: 
    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_SpaceIDto_SpaceID copy|replicate repository:no-security-filters
      • The repository:no-security-filter command 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_SpaceIDto_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_SpaceIDto_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: This does not copy over space membership.
    Note: setting-permissions and custom-subject-areas-no-permissions;packages-no-permissions;networks-no-permissions options should not be used together in a single command. If you need to use the commands together in the same single command, permissions must be applied.
  • 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_SpaceIDto_spaceID copy|replicate stories
  • tags: Copy/replicate Report Catalog tags.copyspace from_SpaceIDto_spaceID copy|replicate tags.
    Caution: 
    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_SpaceIDto_spaceID copy|replicate translations
  • themes: Replicates the theme that is selected for the space.copyspace from_SpaceIDto_SpaceID replicate themes.
    Caution: 
    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_SpaceIDto_SpaceID replicate catalog

  • To replicate the custom subject areas "csa1" and "csa2" from one space to another:
copyspace from_SpaceIDto_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_SpaceIDto_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_SpaceIDto_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_SpaceIDto_SpaceID copy catalog:shared/collection_folder_name

Data driven dashboard conditions can be copied using the catalog option. For example: copyspace sourceSpace targetSpace replicate catalog

dropuserfromspace

Removes a user from a space.

dropuserfromspace username space_name

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.

getspaceid

Get the ID for a space name.

getspaceid space_name

listusersinspace

List users in the space.

listusersinspace space_name

Example:

listusersinspace "Acme Labs Space"

rebuildapplication

Rebuilds an entire application or repository for the selected space. 

rebuildapplication
Note: Space administrators and space owners can use 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.

setspacessopassword

Set the space SSO password.

setspacessopassword spaceID password

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

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

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