Creating and Managing Devices

A device specifies the format of a MicroStrategy report or document and the transmission process to send the report or document to users who subscribe to that report or document.

For example, if you want to send reports via email, and your recipients use an email client such as Microsoft Outlook, you can create a Microsoft Outlook email device that has settings appropriate for working with Outlook. If you need to send reports to a file location on a computer on your network, you can create a file device specifying the network file location. If you want to send reports to a printer on your network, you can create a printer device specifying the network printer location and printer properties.

In Developer, you can create the following types of devices:

• Email: An email device automatically sends a report or document in the form of an email to an email address. It can also send the report in the form of a user-selected file format as an attachment with the email.
• File: A file device automatically sends a MicroStrategy report or document in a file format that the user chooses when subscribing to the report, to a file delivery location on a computer on your network. Users can choose from the following file formats: CSV (comma-separated values), PDF, HTML, MS Excel, and plain text. When a user subscribes to a report or document, the file device sends the report or document to the specified location when the subscription requires it to be sent. You can specify your network file location and file properties for the file device to deliver the file to. For steps to create a file device, see Creating a File Device.
• Print: A print device automatically sends a report or document to a specified printer on your network. You can define the printer properties for the default print device or you can use the standard printer defaults. For steps to create a print device, see Creating a Print Device.
• FTP: An FTP device automatically sends a MicroStrategy report or document, in a file format the user chooses, to a delivery location on an FTP server. Users can choose from the following file formats: CSV (command separated values), PDF, HTML, MS Excel, and plain text. Users subscribe to a report or document, which triggers the FTP device to send the report or document to the specified location when the subscription requires it to be sent. For steps to create an FTP device, see Creating an FTP Device.
• Mobile: iPad or iPhone devices automatically send a report or document to a user's iPad or iPhone. For steps to create a mobile device, see Creating an iPhone/iPad Device These subscriptions are available if you have MicroStrategy Mobile or MicroStrategy Library. To support mobile subscriptions, see Upgrading the API for the Apple Push Notification Service to Support Mobile Subscriptions.

You create new devices when you need a specific combination of properties and settings for a device to deliver files. You can create a new device in two ways. You can either create a completely new device and enter all the supporting information for the device manually, or you can duplicate an existing device and edit the supporting information so it suits your new device. You create and configure devices using the Device Editor.

Devices can be created in a direct connection (two-tier) mode, but print and file locations for those devices are not validated by the system. Print and file locations for devices created when in server connection mode (three-tier) are automatically validated by MicroStrategy.

Recommended Maintenance Tasks for Devices

• Periodically verify all delivery locations to be sure they are active and available.
  • For file delivery locations, use the Device Editor's File: General tab and File: Advanced Properties tab.
  • For printer locations, use the Device Editor's Print: General tab and Print: Advanced Properties tab.
  • For FTP locations, use the Device Editor's FTP: General tab.
• Test a delivery using each device to make sure that the device settings are still effective and any system changes that have occurred do not require changes to any device settings.
• If you experience printing or delivery timeouts, use the Device Editor's File: Advanced Properties tab and Print: Advanced Properties tab to change timeout, retry, and other delivery settings.

Best Practices for Working with Devices

• You can allow users to select their own file delivery or print locations. Use the Device Editor's File: General tab and Print: General tab to allow user-defined file delivery and print locations. Any user-defined location overrides the primary file delivery or print location specified in the File Location or Printer Location field, which, in turn, overrides any backup file delivery or print location specified in the File: Advanced Properties tab or Print: Advanced Properties tab.
• If you have a new email client that you want to use with Distribution Services functionality, create a new email device and apply settings specific to your new email application. To create a new device quickly, use the Duplicate option and then change the device settings so they suit your new email application.
• If you rename a device or change any settings of a device, test the device to make sure that the changes allow the device to deliver reports or documents successfully for users.

Viewing and Modifying a Device and Accessing the Device Editors

Use the Device Editor to view and modify the definition of a device, rename the device, and so on.

To View a Device or Change its Settings

1. From the Developer Folder List, go to Administration > Delivery Managers > Devices.
2. In the Device List area on the right, right-click the device that you want to view or change settings for, and select Edit.
3. Change the device settings as desired.
4. Click OK.

To rename a device, right-click the device and select Rename. Type a new name, and then press Enter. When you rename a device, the contacts and subscriptions using the device are updated automatically.

Creating a File Device

A file device can automatically send a report or document in the form of a file to a storage location such as a folder on a computer on your network. Users subscribe to a report or document that triggers the file device to send the subscribed report or document to the specified location when the subscription requires it to be sent.

You create a new device when you need a specific combination of properties and settings for a file device to deliver files.

You must specify the file properties and the network file location for the file device to deliver files to. You can include properties for the delivered files such as having the system set the file to Read-only, label it as Archive, and so on.

A quick way to create a new file device is to duplicate an existing device and then edit its settings to meet the needs for this new device. This is a time-saving method if a similar device already exists, or you want to duplicate the default MicroStrategy file device. To duplicate a device, right-click the device that you want to duplicate and select Duplicate.

To Create a New File Device

1. From the Developer Folder List, go to Administration > Delivery Managers > Devices.
2. Right-click in the Device List area on the right, select New, and then Device.
3. Select File and click OK.
4. Change the device settings as desired.
5. Click OK.

Once the file device is created, it appears in the list of existing file devices when you create an address (in this case, a path to a file storage location such as a folder) for a MicroStrategy user or a contact. You select a file device and assign it to the address you are creating. When a user subscribes to a report to be delivered to this address, the report is delivered to the file delivery location specified in that address, using the delivery settings specified in the associated file device.

Default File Locations and Permissions

When a new device is created the following default values are applied to the file. They can be accessed from the Device Editor: File window:

The ACL of a file is largely determined by the parent folder (and recursively to the root drive) which is determined before delivery. The administrator is responsible for setting the ACL of the parent folder to meet specific security needs.

General Tab

• File Location: <MicroStrategy Installation Path>\FileSubscription
• File System Options: The Create required folders and Append timestamp to file name options are enabled.

Advanced Properties Tab

• Windows: The Read only checkbox will be enabled.
• Unix/Linux: Access rights for the file will be set to rw-r--r--

Personalizing File Locations

You can dynamically specify the File Location and Backup File Location in a file device using macros. For example, if you specify the File Location as C:\Reports\{&RecipientName}\, all subscriptions using that file device are delivered to subfolders of C:\Reports\. Subscribed reports or documents for each recipient are delivered to a subfolder with that recipient's name, such as C:\Reports\Jane Smith\ or C:\Reports\Hiro Protagonist\.

The table below lists the macros that can be used in the File Location and Backup File Location fields in a file device:

Description	Macro
Date on which the subscription is sent	{&Date}
Time at which the subscription is sent	{&Time}
Name of the recipient	{&RecipientName}
User ID (32-character GUID) of the recipient	{&RecipientID}
Distribution Services address that the subscription is delivered to	{&AddressName}
File path that a dynamic recipient list subscription is delivered to	{&RecipientList Address}

You can also have a subscription dynamically create subfolders according to attributes in a report's page-by axis or a document's group-by area and place the report or document there. For steps, see Creating Subscriptions.

Delivering Files from a UNIX Intelligence Server to a Windows File Location

If your Intelligence Server machine is using UNIX or Linux, you can configure your system to deliver files to locations on Windows machines.

This process uses Sharity software to resolve the Windows file location as a mount on the UNIX machine. Intelligence Server can then treat the Windows file location as though it were a UNIX file location.

To Set Up File Delivery from a UNIX Intelligence Server to a Windows Location

1. Make sure Sharity is configured on the Intelligence Server machine.
2. Create a new file device or edit an existing file device (see Creating a File Device).
3. In the File Device Editor, on the Cross-Platform Delivery with Sharity™ tab, select the Enable delivery from Intelligence Server running on UNIX to Windows check box.
4. In the User Name field, type the Windows network login that is used to access the Windows file location for mounting on the Intelligence Server.
5. In the Password field, type the password for that user name.
6. In the Mount Root field, type the location on the Intelligence Server machine where the mount is stored. Make sure this is a properly formed UNIX path, using forward slashes / to separate directories. For example:
   /bin/Sharity/Mount1
7. Click OK.

Creating an Email Device

An email device automatically sends emails, which contain reports or documents that have been subscribed to by users, or for users by other users or administrators. You create a new email device whenever you need a specific combination of properties and settings to deliver files via email. For example, an email sent through Microsoft Outlook requires a device with settings that are different from an email sent through a web-based email account.

You can specify various MIME options for the emails sent by an email device, such as the type of encoding for the emails, the type of attachments the emails, can support, and so on.

A quick way to create a new email device is to duplicate an existing device and then edit its settings to meet the needs for this new device. This is a time-saving method if you have a similar device already created, or you want to make use of the default MicroStrategy email device. To duplicate a device, right-click the device that you want to duplicate and select Duplicate.

An understanding of your organization's email server or other email delivery systems.

To Create a New Email Device

1. From the Developer Folder List, go to Administration > Delivery Managers > Devices.
2. Right-click in any open space in the Device List area on the right, select New, and then Device.
3. Select Email and click OK.
4. Change the device settings as desired.
5. Click OK .

Once an email device is created, it appears in the list of existing email devices when you create an address for a MicroStrategy user or a contact. You select an email device and assign it to the address you are creating. When a user subscribes to a report to be sent to this address, the report is sent to the email recipient specified in that address, using the delivery settings specified in the associated email device.

Creating a Print Device

A print device sends a report or document to a specified network printer, where the report or document is automatically printed. You create a new print device whenever you need a specific combination of properties and settings to deliver files to a printer. You can create a new print device, define new printer properties for the default print device that comes with MicroStrategy, or use the default device with its default printer settings.

If you are creating a print device to deliver a report or document to a dynamic recipient list, you can dynamically specify the printer location using the {&RecipientListAddress} macro. When the subscription is run, the macro is replaced with the Physical Address specified in its dynamic recipient list. For more information on dynamic recipient lists, see Creating Subscriptions.

The selected printer must be added to the list of printers on the machine on which Intelligence Server is running.

To Create a New Print Device

1. From the Developer Folder List, go to Administration > Delivery Managers > Devices.
2. Right-click in the Device List area on the right, select New, and then Device.
3. Select Print and click OK.
4. Change the device settings as desired.
5. Click OK.

Once a print device is created, it appears in the list of existing print devices when you create an address (in this case, a path to the printer) for a MicroStrategy user or a contact. You select a print device and assign it to the address you are creating. When a user subscribes to a report to be sent to this address, the report is sent to the printer specified in that address, using the delivery settings specified in the associated print device. For details on creating an address for a user or on creating a contact and adding addresses to the contact, click Help.

Creating an FTP Device

An FTP device automatically sends a report or document in the form of a file to a location on an FTP server. Users subscribe to a report or document, which triggers the FTP device to send the subscribed report or document to the specified location when the subscription requires it to be sent.

You create a new device whenever you need a specific combination of properties and settings for an FTP device to deliver files.

A quick way to create a new FTP device is to duplicate an existing device and then edit its settings to meet the needs for this new device. This is a time-saving method if you have a similar device already created, or you want to make use of the default MicroStrategy FTP device. To duplicate a device, right-click the device that you want to duplicate and select Duplicate.

To Create a New FTP Device

1. From the Developer Folder List, go to Administration > Delivery Managers > Devices.
2. Right-click in the Device List area on the right, select New, and then Device.
3. Select FTP and click OK.
4. Change the device settings as desired.
5. Click OK.

Once the FTP device is created, it appears in the list of existing FTP devices. When you create an address for a MicroStrategy user or a contact, you can select an FTP device and assign it to the address you are creating. When a user subscribes to a report to be delivered to this address, the report is delivered to the delivery location specified in that address, using the delivery settings specified in the associated FTP device. For details on creating an address for a user or on creating a contact and adding addresses to the contact, click Help.

Creating an iPhone/iPad Device

An iPhone/iPad delivery device is used to automatically push real-time updates of reports or documents to a user's iPhone/iPad, when the report or document is updated. Users subscribe to a report or document, which triggers the iPhone/iPad device to send the subscribed report or document to the user's iPhone/iPad.

You create a new device whenever you need a specific combination of properties and settings for an iPhone/iPad device to deliver reports or documents.

A quick way to create a new iPhone/iPad device is to duplicate an existing device and then edit its settings to meet the needs for the new device. This is a time-saving method if you have a similar device already created, or you want to duplicate the default MicroStrategy iPhone/iPad device. To duplicate a device, right-click the device that you want to duplicate and select Duplicate.

To Create an iPhone/iPad Device

1. In Developer, from the Folder List on the left, go to Administration > Delivery Managers > Devices.
2. Right-click in the Device List area on the right, select New, and then Device.
3. Select Mobile Client iPhone or Mobile Client iPad and click OK.

4. The default APNS server address and port number are api.push.apple.com and 443, as shown below.

   

After an iPhone/iPad delivery device is created, you see it in the list of existing iPhone/iPad devices when you create an address for a MicroStrategy user or a contact. You select an iPhone/iPad device and assign it to the address you are creating. When a user subscribes to a report to be delivered to this address, the report is delivered to the iPhone/iPad specified in that address, using the delivery settings specified in the associated iPhone/iPad device.

Deleting a Device

You can delete a device if it is no longer needed.

To Delete a Device

1. From the Developer Folder List, go to Administration > Delivery Managers > Devices.
2. In the Device List area on the right, right-click the device you want to delete.
3. Select Delete.

Upgrading the API for the Apple Push Notification Service to Support Mobile Subscriptions

Starting in MicroStrategy 2020 Update 2, the Intelligence server supports the HTTP/2-based APNS API to send remote notification requests to Apple devices. The legacy protocol is no longer supported starting in November 2020.

If you are upgrading from 11.2.x to 11.3, you must upgrade the metadata. If the mobile device already exists in the metadata, the server name and port number are changed dynamically to adapt to the new API. No manual work is necessary.

You can also update the default value for the server name and port number by editing the mobile device through Developer, using the procedure below.

To modify the iPhone/iPad device

1. In Developer, from the Folder List on the left, go to Administration > Delivery Managers > Devices.
2. Right-click a device and select Edit.

3. Enter your device settings.

   

4. Click OK.

After upgrading to the new API, the Apple feedback server is no longer used, since the APNS server sends per-notification feedback to the Intelligence server. Developer hides the APNS feedback service.

Now the default push notification server address has been upgraded for the server using the new API.