Configure bicep parameters

To deploy Azure resources (i.e. App services, Databases) you need to create a bicep parameter file. To prepare your parameter file, you need to find values for your parameters. Please follow following steps and note down parameter values.

Step-1: Find your clientId, tenantId and audience

1. Go to Azure Entra ID.

2. Under overview tab, you'll find tenant Id. Please take note of the tenantId

   

3. Then from left menu, click App registrations. Select All application tab, then find for your Analytics UI app registration. Please take note of the Application (client) ID. Then click on the app. (Similarly, take note of the Application (client) ID for the Analytics API app registration)

   

4. Go to the app registration for the API and copy the Application ID URI. Please take note of this value, because this is the value for your audience parameter

   

Step-2: Take note of custom domain related parameters

Please note down the names of resource group, key vault and certificates that you've used/created in this pre requisites step.

Now, please take note of custom domain name you've created in the pre-requisite step.

Step-3: Take note of parameters for SQL server admin

1. Go to Azure Entra ID

2. Then from left menu, click on Users.

   

3. Search for the user who you want to be your SQL server Entra admin.

   

4. Please take note of User principle name and Object ID

   

Step-4: Get ILAP data exchange (IDE) API parameters

We fetch relevant ILAP terms (Fields in Ilap analytics) from ILAP data exchange API. For that we have to configure some parameters. First, take note of the IDE Api URL from below for your target environment (i.e. If you want to fetch fields from IDE beta environment then use beta Url).

Now, to access IDE API, ILAP analytics needs an access token. We can use service token. We can generate IDE API access token from web UI page using the following steps.

1. Go to IDE UI of your target environment. (For URL, refer to the table above)

2. After login, go to Tenant Admin page. Click on Clients. Select ILAP Analytics

3. Click Add New Component. (You can ignore this step if you already have a component.)

4. Now, create the client by giving it some name and description.

   

5. Click on the three-dot menu on right of the client you've just created. Select Service Tokens.

   

6. Then click on Add New Token

   

7. Select an expiry date for the token, please note that you will have to create and register a new token for the Analytics Client prior to this expiration date. The generated token needs to be stored securely as it can be used to access data within your tenant.

   

8. Click on Create

   

9. Click on the Copy link and store the access token in a secure place. Also take a note of the instance Id after you click ok.

   

Step-5 (optional): Use AAD authentication for swagger

For quick investigations, Swagger is a handy tool. However, it usually requires you to enter the Bearer token manually. To make this easier, we've added support for interactive authentication — the same way you log in through the web UI. To enable this, you'll need to configure the SwaggerAzureAdAuthOptions parameter. Follow the steps below to obtain the required values. Note: You may not want to do this for production environment

1. Go to your Azure Entra ID. Find API app registration. Click on Endpoints, note down AuthorizationUrl and TokenUrl

   

2. From left menu, go to Expose an API tab. Note down name and description (display name) of the scopes

   

3. Now, go to web UI app registration. Copy the client ID. It will be used for SwaggerClientId parameter.

   

4. Construct swagger redirect URL. Go analytics API app service from Azure App Services. Click on Browse. A new window will open. Copy the URL and use it here.

   https://<your_analytics_api_app_service_url>/swagger/oauth2-redirect.html

5. Add the redirect URL in the UI app registration. Save it.

   

Step-6 (optional): Use AAD authentication for Hangfire Dashboard

1. Go to Azure Entra ID. Find API app registration. Click on Authentication on the side menu.

2. Click on Add platform and select Web (if this platform is not already added).

3. Provide a redirect uri. The uri should be <your_hangfire_app_url>/<redirect_suffix_of_your_choice>. In the example screenshot, the suffix is /signin-oidc. It does not have to be strictly this. Note the suffix that you chose for this step. It will be required in the bicep.

4. Feel free to add more redirect uri if you want to support multiple environments. But you must use the same suffix.

5. Enable ID tokens to allow for implicit and hybrid flows.

6. You can restrict the access to Hangfire dashboard to only selected roles. In that case, assign app roles and note down the Value(s). In a later step, in the bicep parameter, you will put them in the AllowedRoles list.

7. You are all set. Make sure to set enableHangfireAzureAdAuth to true in the bicep parameter. Now the hangfire dashboard access will require AAD authentication.

Set bicep parameter

At this point you have everything you need to create parameter file. Create a file with .bicepparam extension. Dump the following code into the file. Update parameters as mentioned in the comments.

Note: The following Bicep parameters can also be found in the main.sample.bicepparam file located in the Azure.IaC folder you downloaded from the installation center.

using 'main.bicep'

var env = 'dev'  // Your environment name. Example: test, beta, prod etc.

var company = 'promineo'  // Your company name

param azureAd = {

  clientId: 'application client id of UI app registration' // Client id from step-1

  instance:'https://login.microsoftonline.com/'

  tenantId:'your_tenant_id' // Use tenant id from step-1

  audience:'analytics_api_audience_id' // Use audience from step-1
}

// Note: these values configure the UI at deploy time via app-service environment variables. They
// replace the legacy PublicConfigurations.js file, which is obsolete.

param publicConfigurations = {

  analyticsApiUrl: // Base URL of your ILAP analytics API app,

  //If you are using custom domain for analytics API, then use custom domain URL(+ '/api) here, instead of the default URL (i.e. URL that contains "[app-name].azurewebsites.net")

  // for example: 'https://app-ilapanalytics-api-dev.azurewebsites.net/api' or 'https://analytics-api.promineo.com/api'

  backgroundJobAppUrl: Base URL of your ILAP analytics background job app

// Example: 'https://app-ilapanalytics-backgroundjobs-dev.azurewebsites.net'. You can find the URL by clicking browse from azure app service.

  authenticationAuthority: //'https://login.microsoftonline.com/[your tenant id]/' for example: 'https://login.microsoftonline.com/8719bf0f-72ad-48f5-ba9d-da3dbbcd7509/'

  authenticationClientId: //'application client id of UI app registration'

  authenticationScopes: //'comma separated scopes from your API app registration' for example: 'api://970d7cfa-159b-45cd-9f97-9781b00e6624/user_impersonation,api://970d7cfa-159b-45cd-9f97-9781b00e6624/read'

  authenticationRedirectUri: //'your-ilapanalytics-ui-base-url'. // Base URL of your ILAP analytics UI app,

  //If you are using custom domain for analytics UI, then use custom domain URL here, instead of the default URL (i.e. URL that contains "[app-name].azurewebsites.net")

  ideUiBaseUrl: // Base URL of the ILAP Data Exchange (IDE) web UI, used to build links to IEAs. Use IDE UI Url from step-4. For example: 'https://ilaptest.collabor8.no' for test, 'https://ilap.collabor8.no' for production

}

// Note: if useCustomDomain is false, then leave customDomain and certficateName parameters as is.

// Note: if you are using custom domain for analytics API, then you must use custom domain URL in IDE connector, instead of the default URL (i.e. URL that contains ".azurewebsites.net")

param webAppParams = {

  ilapAnalyticsUi: {

    name: //Enter any name for your ILAP analytics web UI app. For example: 'app-promineo-ilapanalytics-ui-dev'

    customDomain: //Enter custom domain name for analytics web UI app. // For example: 'analytics-ui.promineo.com' if you're not using custom domain, put any random string here

    certificateName:   // Certificate name from Step-2. Applicable only if you are using custom domain

    useCustomDomain:  // If you do not want custom domain for Api then make it false

  }

  ilapAnalyticsApi: {

    name: //Enter any name for your ILAP analytics web API app. For example: 'app-promineo-ilapanalytics-api-dev'

    customDomain: //Enter custom domain name for analytics web API app. // For example: 'analytics-api.promineo.com' if you're not using custom domain, put any random string here

    certificateName: //Certificate name for API  Applicable only if you are using custom domain

    useCustomDomain:   // If you do not want custom domain for Api then make it false

  }

  ilapAnalyticsBackgroundJob: {

    name: //Enter any name for your ILAP analytics background job app. For example: 'app-promineo-ilapanalytics-bg-dev'

    customDomain: //Enter custom domain name for background job app. // For example: 'analytics-bg.promineo.com' if you're not using custom domain, put any random string here

    certificateName: //Enter certificate name for BackgroundJobs app  Applicable only if you are using custom domain

    useCustomDomain:  // If you do not want custom domain for BackgroundJobApp then make it false

  }
}

param timephasingServiceConfiguration = {

    BaseUrl: 'https://timephasing.promineo.com'

    AccessToken: 'Your_Access_Token' // Access token from time phasing service. Go to https://timephasing.promineo.com For more details.

    MaxNumberOfActivitiesPerRequest: 2000 // Maximum number of activities to send in a single request. Feel free to adjust based on your need.

    IncludePerCalendar: false // To fetch calendar hours from time phasing. You can make it true if calendar hours related changes in timePhasing dev merged into main

}

param dataValidationConfiguration = {

  MaxIncrementLimit: 10 // In percentage

}

param databaseParams = {

  name: //Enter any name for ilap analytics database. For example: 'promineo-sqldb-ilapanalytics-dev-norwayeast'

  backupStorageRedundancy: 'Zone'// Use 'Zone' in prod. for dev environment you can use 'Local' to save cost.

  minCapacity: '2' // Use at least 2 in prod. For dev environment you can use '1' to save cost

  isZoneRedundant: true

  sku: {                 // Feel free to adjust based on your need.

    name: 'HS_S_Gen5' // Hyperscale Gen5 is recommended for production. For dev environment you can use S3

    tier: 'Hyperscale'

    family: 'Gen5'

    capacity: 8

  }

}

// Specifies the number of database entities to process per batch during read and write operations.

param dbOperationSettings = {
  ReadBatchSize: 15000
  WriteBatchSize: 10000
}

param archiveDatabaseParams = {

  name: //Enter any name for ilap analytics archive database. For example: 'promineo-sqldb-ilapanalytics-archive-dev-norwayeast'

  backupStorageRedundancy: 'Zone' // Use 'Zone' in prod. for dev environment you can use 'Local' to save cost.

  minCapacity: '2'// Use at least 2 in prod. For dev environment you can use '1' to save cost

  isZoneRedundant: true

  sku: {                 // Feel free to adjust based on your need.

    name: 'HS_S_Gen5'    //Hyperscale Gen5 is recommended for production. For dev environment you can use S3

    tier: 'Hyperscale'

    family: 'Gen5'

    capacity: 8

  }

}

var defaultAppServicePlanSku = { // Service plan SKU for all app services. in this sample we're using the same SKU for all app services.

// In order to save cost, you can use different SKU for the web ui

  name: 'P3v2'

  tier: 'PremiumV2'

  size: 'P3v2'

  family: 'Pv2'

}

param apiAppServicePlanName = 'Enter any name for ilap analytics api app service plan'

param bgAppServicePlanName = 'Enter any name for ilap analytics background job app service plan'

param webAppServicePlanName = 'Enter any name for ilap analytics web UI app service plan'

param appServicePlanParams = [
  {
    name: apiAppServicePlanName
    sku: defaultAppServicePlanSku
  }
  {
    name: bgAppServicePlanName

    sku: defaultAppServicePlanSku
  }
  {
    name: webAppServicePlanName
    sku: defaultAppServicePlanSku
  }
]

// Note: ILAP Analytics uses Azure AD-only authentication (azureADOnlyAuthentication: true). The SQL
// username/password administrator fields (administratorLogin / administratorLoginPassword) are
// obsolete for new customers and are no longer used.
param sqlServerParams = {

  name: //Enter any name for sql server. For example: 'promineo-sqlserver-ilapanalytics-dev-norwayeast'

  administrators: {

    administratorType: 'ActiveDirectory'

    azureADOnlyAuthentication: true

    principalType: 'User'

    login: //Enter sql server admin email (user principal name from step-3)

    sid: //Enter user Id of sql server admin (object ID from step-3)'.

    tenantId: //Enter tenant ID (tenant Id from step-1)

  }

}

// If you are not using any custom domain, then ignore the following param

param keyVaultParams = {

  name: //Enter name of the keyvault which stores certificates for custom domain (Key Vault name from step-2). for example: 'promineo-kv-ilapanalytics-dev-norwayeast'

  resourceGroupName: //Enter resource group name (resource group name from step-2). for example: 'promineo-rg-ilapanalytics-dev-norwayeast'

}

param moveIlapFileToBlobStorage = 'false'  // Ilap files are deleted from Database after background jobs are completed. So, if you want to store Ilap files to above storage account then make it 'true'.

// If you do not want to move ILAP file to blob storage (in other words if moveIlapFileToBlobStorage param is false), then please ignore the following param

param storageAccountParams = {

  name: //Enter any storage name. For example: 'promineoilapanalyticsdevstorage'

  kind: 'StorageV2'

  sku: {               // Feel free to adjust based on your need.

    name: 'Standard_LRS'

    tier: 'Standard'
  }
}

param ideApiBaseUrl = 'https://dev.ilapdataexchange.promineo.no/api/api' // IDE API URL from step-4

param ideApiAccessToken = 'eyJhbGciOiJIUzI..........' // Access token from step-4

param synchronizeFieldsJobSchedule = '*/10 * * * *' // Means: Every 10 minutes. It specifies how often background job will fetch ILAP terms from IDE.

param graphQlExecutionTimeout = '15' // In munites

param enableFieldSyncronization = 'true' // To syncronize ilap terms (aka. metadataFields) with IDE

param enableFieldImport = 'true' // To import ilap terms (aka. metadataFields) from IDE

param SendJobStatusToIDE = 'false' // Send background job operation status to IDE

param instanceInformation = {

  Identifier: 'Identifier guid of your ILAP Analytics component in IDE' // Analytics client Identifier from IDE.
  // Go to IDE web page -> Tenant Admin -> Clients -> ILAP Analytics -> Copy Identifier column value

}

param planningScheduleDeleteConfiguration = {

  // Set to 'true' to automatically delete planning schedules that are no longer referenced by any report schedule.

  PlanningScheduleAutomaticDeletion: false

  // Specifies the retention period (in days) for unreferenced planning schedules

  // before they are deleted from the database.

  PlanningScheduleRetentionPeriodInDays: 7

}

param reportScheduleArchiveConfiguration = {

  // Set to 'true' to enable automatic archiving of closed report schedules.

  EnableReportScheduleAutomaticArchive: false

  // Defines how long (in days) closed report schedules should remain in the database

  // before being moved to the archive.

  ReportScheduleRetentionPeriodInDays: 7

  // Number of report schedule records to process in a single batch when archiving.

  // Reduce this value to decrease the load on the application and database,

  // but note that smaller batches may increase total archive time.

  QueryBatchSize: 3000

}

// Swagger Azure AD Authentication Options. If you don't want to use Azure AD authentication for Swagger UI, then leave the following parameters as is.
// Refer to Step 5 for instructions on how to obtain these values

param SwaggerAzureAdAuthOptions = {

  AuthorizationUrl: ''
  TokenUrl: ''
  SwaggerClientId: ''
  Scopes: [
    {
      Name: ''
      Description: ''
    }
    {
      Name: '' // Get from Azure Entra ID API app registration scopes from "Expose an API" tab
      Description: ''
    }
  ]
}

// Operation completion notifications
// Controls whether applications publish a notification to event hub when a report schedule import/revert is completed.
// Notes:
// - If you plan to enable this, configure the "eventhubConfig" block below.
// - If you plan to notify via HTTP callback, set "CallbackHostUrl" to your API host base URL.
param operationCompletionNotificationConfig = {
  // Enable or disable operation completion notifications (true|false)
  IsEnabled: false
  // Notification type:
  //      1 = Report Schedule Id Only,
  //      2 = Report Schedule Id With Activity Ids,
  //      3 = Report Schedule Ids With Activity Fqdns
  NotificationType: 2
  // Optional: Base URL for callback endpoints (used when notification type 3 is selected)
  CallbackHostUrl: publicConfigurations.analyticsApiUrl

  // Number of notifications to send in a single batch
  /*
    | Event hub pricing tier | Basic  | Standard | Premium | Dedicated |
    |------------------------|--------|----------|---------|-----------|
    | Batch size to use      | ~2000  | ~6000    | ~6000   | ~150000   |
  */
  BatchSize: 2000
}

// Event Hub configuration (optional, mandatory if operation completion notifications are enabled above)
// Provide only if you plan to publish operation completion notifications to an Azure Event Hub.
// - NamespaceUrl: The fully qualified namespace host (e.g., "your-namespace.servicebus.windows.net").
// - EventhubName: The Event Hub name to which events will be emitted.
// Note: Ensure that the application has the necessary permissions to send events to the specified Event Hub.
param eventhubConfig = {
  NamespaceUrl:// 'your-namespace.servicebus.windows.net'
  EventhubName: //'name-of-your-eventhub'
}

// Set to 'true' to enable Azure AD authentication for Hangfire dashboard.
// If set to 'false', then basic authentication will be used.
param enableHangfireAzureAdAuth = 'false'

param hangfireCredentials = {
  Username: 'admin' // provide your desired username
  Password: 'QwK?9MLzK+9UJjRT' // provide your desired strong password
}

// Only applicable if enableHangfireAzureAdAuth is set to 'true'.
param hangfireAzureAdAuthOptions = {
  Instance: 'https://login.microsoftonline.com/'
  TenantId: 'your_tenant_id'
  ClientId: 'analytics_api_client_id_from_step-1'
  CallbackPath: '/signin-oidc' // Your web platform redirect URI from Azure Entra app registration
  AllowedRoles: ['Administrator'] // List of roles allowed to access Hangfire dashboard. Leave empty if all authenticated users are allowed.
}

Bicep Parameter File Documentation (Tabular Format)

This table provides a detailed overview of the parameters and variables in the Bicep parameter file for configuring an ILAP analytics application deployment on Azure. It is designed to help new users understand each parameter's purpose, default values, significance, and examples.

Notes

• Custom Domains: If useCustomDomain is false, leave customDomain and certificateName as is (e.g., random string for customDomain). Use custom domain URLs in the IDE connector for APIs if enabled.
• Blob Storage: storageAccountParams is relevant only if moveIlapFileToBlobStorage is 'true'.
• Cost Optimization: Use 'Local' for backupStorageRedundancy, '1' for minCapacity, or S3 SKU in development to save costs.