Setting up connectors

Creating a File Storage connector

Modified on Tue, 17 Nov at 12:02 AM

TABLE OF CONTENTS

  1. Introduction
  2. At a glance
  3. What to ask your IT administrator for
  4. Open the connector wizard
  5. Step 1: General
  6. Step 2: Components
  7. Step 3: Authentication
  8. Step 4: Settings
  9. Step 5: Complete, test and persist
  10. How SchedEx finds and reads the files
  11. Messages and what to do
  12. Questions and answers
  13. Related articles

Introduction

This article shows you, step by step, how to create a File Storage connector. This connector lets SchedEx read schedule files from a container in Microsoft Azure Blob Storage that your organization owns, and send them to your partners through an Exchange Agreement.

The files must be SchedEx exchange files: files that end in .ilap. Each file holds one complete schedule. Something outside SchedEx puts the files in the container, for example an export job that your IT department runs. SchedEx only reads them.

Who can do this: a user with the Tenant Setup role in SchedEx.

You do not need to be technical. The values come from your IT department or the person who manages your Azure storage. Section 2 lists exactly what to ask them for.

Not sure this is the right connector? The File Storage connector is not the same as the storage choices of the Microsoft Project, Excel and Primavera P6 XER connectors (Web Storage, SharePoint or Local File). Those connectors read .mpp, .xlsx and .xer files. The File Storage connector reads only .ilap files, and only from your own Azure storage. See Choosing where your schedule files are stored and section 1 below.


1. At a glance

Creating the connector takes about five minutes once you have the values from your IT department.

  1. Ask your IT department for the values in section 2.
  2. Fill in the five-step wizard in SchedEx (sections 3 to 7).
  3. Test and persist the connector (section 8).

What the File Storage connector does and does not do

File Storage connector
Where the files are In a container in your organization's Azure Blob Storage.
Which files Only files that end in .ilap. Other files in the container are ignored.
Send or receive Send only. You can use it on the sending side of an Exchange Agreement. It cannot receive data, so SchedEx never writes to your container.
Who puts the files there Your organization, outside SchedEx. SchedEx has no upload page for this connector.
Which SchedEx program reads them The Desktop Client, the Autonomous Component, or both. You choose in Step 2.

When to choose it

Choose File Storage when your schedules already exist as .ilap files in your own Azure storage, and you want SchedEx to send them as they are.

Choose a different connector when:

  • Your files are .mpp, .xlsx or .xer files. Use the Microsoft Project, Excel or XER file connector. Those connectors can keep files in SchedEx itself (Web Storage), on SharePoint, or in a local folder. See Choosing where your schedule files are stored.
  • You want to receive data into a file. File Storage cannot receive.
  • Your planning tool has a live connection to SchedEx (for example Primavera P6 EPPM or Safran). A live connector is usually the better choice.

Checklist before you open the wizard:

  • I know the storage account and the container that hold the .ilap files.
  • I have a Blob Connection String, or my IT department has set up managed identity access (section 2).
  • I know the folder inside the container, if the files are not at the top level.
  • I know whether transfers run on a person's PC (Desktop Client), on a server (Autonomous Component), or both.

2. What to ask your IT administrator for

Ask your IT department, or the person who manages your Azure storage, for the items below. Tell them that SchedEx only needs to read and list files in one container. It never writes, changes or deletes files there.

Ask for Why SchedEx needs it Where it goes
The name of the container that holds the .ilap files. It uses lowercase letters, numbers and hyphens only. So SchedEx knows which container to look in. Step 3: Blob Container Name (connection string method)
Only if you use the connection string method: a connection string for the storage account. In the Azure portal it is under Storage account → Access keys. It starts with DefaultEndpointsProtocol=https;AccountName=... So SchedEx can sign in to the storage account. Step 3: Blob Connection String
Only if you use managed identity: the container address (endpoint), in the form https://<account>.blob.core.windows.net/<container>. So SchedEx can find the container. Step 3: Container Endpoint
Only if you use managed identity: read access to the container for the managed identity of the server where the Autonomous Component runs. With managed identity, Azure decides who may read. No password is stored in SchedEx. Set up in Azure by IT
Only if the files are not at the top level of the container: the folder path, for example schedules or data/exports. SchedEx reads files from one folder only. Step 3: Blob Folder Name
Confirmation that the storage account can be reached from users' PCs or the Autonomous Component's server. SchedEx connects to Azure directly from there. Storage firewalls can block it. Network, set up by IT
Who puts the .ilap files in the container, and how often. SchedEx sends whatever file is there when a transfer runs. Agreed with the file owner

Treat the connection string like a password. It gives access to the whole storage account. Where your setup allows it, the managed identity method is the safer choice because no secret is stored in SchedEx.

How SchedEx keeps these values safe: passwords, client secrets and tokens entered in connector wizards are encrypted with AES-256 before SchedEx saves the connector, with the key kept in Azure Key Vault. The connection string of a File Storage connector is not encrypted yet, so treat access to SchedEx Setup as you would access to the storage account. Read more in Checking your connectors.


3. Open the connector wizard

  1. Select Setup in the top menu.
  2. On the Connector List card, select New Connector.

The Setup page with the New Connector button on the Connector List card The Setup page. New Connector is on the Connector List card.

The New Connector wizard opens on the right. It has five steps: General, Components, Authentication, Settings and Complete. Every field has an ⓘ icon. Point at it to see a short help text. Next stays grey until every required field on the step is filled in.


4. Step 1: General

Field What to enter
Connector Name (required) A name that tells your colleagues which storage this is, for example Azure schedule files (Production). The name is shown everywhere the connector is used, such as in Configs and Exchange Agreements.
Host System (required) Select File Storage. The card says Connect to Azure Blob Storage.
Import from existing (optional) Copies the settings of a connector you already have, so that you only change what is different.

Step 1 of the wizard with the File Storage card selected Step 1: the File Storage card selected.

Select Next.


5. Step 2: Components

An execution component is the SchedEx program that runs the transfer and reads the files.

Option What it means Choose it when
Desktop Client The SchedEx desktop program on a user's PC. Someone must be signed in to start a transfer. People start transfers by hand.
Autonomous Component A SchedEx service that runs on a server, without a person. Transfers must run automatically on a schedule, or you want to use managed identity.

You can select both. The connector then gets one sign-in profile for each component, and you fill in both in the next step.

Step 2 with both components selected Step 2 with both components selected. Step 3 then shows a tab for each one.

SchedEx connects to Azure directly from where the component runs: the user's PC or the Autonomous Component's server. The storage account must be reachable from there.

Select Next.


6. Step 3: Authentication

If you selected both components in Step 2, you see two tabs: Desktop Client and Autonomous Component. Fill in both. The line at the bottom tells you when the other profile is still incomplete, and Switch to … takes you to it.

First choose the Authentication Method: how SchedEx proves to Azure that it may read the files. The fields below the list change to match your choice, and a short note explains the method.

Method You enter Best for
Blob Storage Connection String Blob Connection String, Blob Container Name, and optionally Blob Folder Name The Desktop Client, and any setup outside Azure
Microsoft Entra Managed Identity Authentication Container Endpoint, and optionally Blob Folder Name The Autonomous Component when it runs in Azure

Selected both components? Use the same method and the same value on both tabs. SchedEx checks that both profiles point to the same place. A connector where the Desktop Client uses a connection string and the Autonomous Component uses managed identity cannot be saved. In practice, that means using Blob Storage Connection String on both tabs.

Option A: Blob Storage Connection String

SchedEx signs in with the storage account's connection string.

File Storage authentication with Blob Storage Connection String selected Blob Storage Connection String: the connection string, container name and optional folder.

Field What it means Example
Blob Connection String (required) The connection string from your IT department. The field hides what you type. DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
Blob Container Name (required) The container that holds the files. schedule-files
Blob Folder Name (optional) The folder inside the container. Leave it empty if the files are at the top level of the container. data/exports

Option B: Microsoft Entra Managed Identity Authentication

No password or key is stored in SchedEx. Azure itself checks that the server where SchedEx runs is allowed to read the container. This only works where Azure can give SchedEx an identity: in practice, an Autonomous Component that runs in Azure.

File Storage authentication with managed identity selected Managed identity: the container endpoint and optional folder.

Field What it means Example
Container Endpoint (required) The full address of the container. It includes the container name, so there is no separate container name field. https://mystorage.blob.core.windows.net/schedule-files
Blob Folder Name (optional) The folder inside the container. Leave it empty if the files are at the top level of the container. data/exports

Managed identity needs set-up in Azure. Your IT department must give the server's managed identity permission to read the container. If they have not, the test fails with an access message (section 10).

Select Next when all required fields are filled in.


7. Step 4: Settings

The File Storage connector has no extra settings. The step only shows the note No additional settings are required for this connector type. Click 'Create Connector' to save.

Settings step for a File Storage connector Step 4: no settings are needed for File Storage.

Select Create Connector to save.

Each connector needs its own storage. Two File Storage connectors for the same component cannot point to the same storage. If you try, you see A connector with this URL or path already exists. SchedEx uses the connector to keep track of transferred activities over time, so it stops you from saving a duplicate.


8. Step 5: Complete, test and persist

The last step confirms that the connector is saved. Select View Connector to open it, or Close.

The connector cannot send data yet. Two things are left:

  1. Test the connector. In the SchedEx desktop client, open Connectors and select Test on the connector's row. SchedEx signs in to Azure and looks for the container or folder.
    • Success! Blob storage found! means the sign-in, the container and the folder all work.
    • Test Failed: followed by a message means something is wrong. See section 10.
    • If you entered a Blob Folder Name, the test only passes when the folder contains at least one file.
  2. Persist the connector. Select Persist on the same row. SchedEx opens every .ilap file in the folder and saves the list of schedules and their fields, so that you can select them in Configs. When it finishes you see Host System data stored successfully!

Persist again when new files arrive. A new .ilap file only appears in Configs after the next persist. A file that is replaced under the same name does not need a new persist: SchedEx reads the file again at every transfer.

Persist opens every file. If the folder holds many large files, persist can take a while.

If transfers run on the Autonomous Component

A test in the desktop client runs from your PC with the Desktop Client profile. It proves that your PC can reach the storage, not that the server where the Autonomous Component runs can. If you use managed identity, the desktop test cannot prove it at all. To check the server:

  • Persist from the server. In the SchedEx web app, open Setup > Connectors, open the connector and select Persist Within 3 Minutes. The Autonomous Component picks up the request and reads the container itself.
  • Ask a Tenant Admin to check the dashboard. In Clients > Autonomous Component > Dashboard, the Connectors panel shows each connector's health and its latest persist. The connector should be Healthy and its persist Completed. If it is Unhealthy, point at the error icon to see why. See Reading the Autonomous Component Dashboard.

Check the connector later

In the web app, Setup > Connectors shows every connector's Status and Last Health Check. A connector that has not been checked for more than 7 days is marked as such: run Test again to refresh it. Test and persist again whenever the connection string, the container or the folder changes.

More about testing and persisting: Testing and Persisting a Connector.


9. How SchedEx finds and reads the files

  • One file is one schedule. After a persist, each .ilap file appears as a schedule that you can pick in a Config. The name shown is the schedule description stored inside the file.
  • Only one folder is read. SchedEx reads the files directly in the Blob Folder Name folder, or at the top level of the container if you left it empty. Files in subfolders are ignored.
  • Only .ilap files are read. Other files in the folder are ignored.
  • The file is read fresh at every transfer. When a Data Transfer runs, SchedEx opens the file for that schedule and sends what is in it at that moment. To send a new version, replace the file under the same name.
  • Do not rename or move a file that an Exchange Agreement uses. SchedEx looks for it by its name and folder, and the transfer fails if it is gone.
  • The fields come from the file. The fields you can map in the Config are the standard schedule fields plus the extra fields found in the files at the last persist. If a file gets new fields, persist again.
  • Filtering is done in the Config. You can limit which activities are sent with the activity filter in the Config, as for other sending connectors.
  • Nothing is written back. SchedEx never adds, changes or deletes files in your container.

10. Messages and what to do

While you fill in the wizard

Message What it means What to do
Blob connection string is required Blob Connection String is empty. Enter the connection string from your IT department.
Blob Container Name is required Blob Container Name is empty. Enter the container name.
Container Endpoint is required Managed identity: Container Endpoint is empty. Enter the full container address.
All execution component configurations of a connector must use the same URL or path. The two tabs in Step 3 point to different places, or use different methods. Use the same method and the same connection string or endpoint on both tabs.
A connector with this URL or path already exists. Please update the URL or path and try saving again. Another File Storage connector already uses this storage for the same component. Use the existing connector, or ask IT for a different storage location.
Next stays grey A required field is empty, or the other component's profile is incomplete. Look for fields marked in red, and check the line at the bottom of the Authentication step.

When you test or persist

Message What it means What to do
Failed! Blob storage does not exist SchedEx signed in, but the container was not found. Check the Blob Container Name or Container Endpoint.
Failed! No folder or no files in the folder exists in Blob storage The Blob Folder Name does not exist, or the folder is empty. Check the folder path (use / between folders). Make sure at least one file is in the folder.
Failed to access the blob container! Please check your connection string, container name and your permission to access the blob. SchedEx could not sign in or could not reach the storage. Check the connection string with IT. With managed identity, ask IT to check the server's read permission. Check that a storage firewall does not block the PC or server.
Blob ConnectionString or ContainerName can not be empty / Blob ContainerEndpoint can not be empty The saved connector is missing a required value. Edit the connector and fill in the field.
This connector test is already running or waiting to start. A test of this connector is already in progress. Wait for it to finish.

When a transfer runs

Message What it means What to do
We couldn't find the schedule file '…'. Please make sure it exists and try again. The file was renamed, moved or deleted since the persist. Put the file back under its old name, or persist again and update the Config to the new schedule.
We couldn't retrieve the schedule file '…'. Please try again. The file exists but could not be downloaded. Try again. If it keeps failing, check access with IT.
The schedule data could not be processed after being retrieved from blob storage because it was empty or invalid. Please contact support. The file is empty or not a valid .ilap file. Ask the file owner to check the file. Contact support if the file looks correct.
Import isn’t supported for File Storage. Someone tried to use the connector on the receiving side. Use File Storage only for sending.

11. Questions and answers

Can I upload .ilap files to SchedEx myself? No. The Upload Files tab in SchedEx is for the Web Storage of the Microsoft Project, Excel and XER connectors. For File Storage, the files go into your own Azure container, outside SchedEx.

Can File Storage receive data from a partner? No. It is send-only. To receive into a file, use the Microsoft Project, Excel or XER file connector.

The connection string changed (the key was rotated). What do I do? Edit the connector, enter the new connection string on the Authentication step (on each tab that uses it) and save. Then run the test again.

Can I use managed identity with the Desktop Client? It is not recommended. Managed identity relies on Azure giving an identity to the machine where SchedEx runs, which a normal user PC does not have. Use Blob Storage Connection String for the Desktop Client.

I added a new file but I cannot select it in the Config. Persist the connector again. New files only appear after a persist.

Can one connector read several folders? No. One connector reads one folder. Create another connector for another folder, and ask IT for a separate storage location if SchedEx reports a duplicate.

Can I change the connector later? Yes. Open the connector and edit it. Run the test and persist again after you change the connection, the container or the folder.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article