Register Data Sources (On-Prem or Private Cloud)

1 Introduction

This guide explains how to use published OData services and external entities with or without the Catalog when deploying locally, to a Private Cloud or an On-Premises solution.

1.1 Use Cases

This document covers the following use cases:

• You are developing both the service and the client on a local machine, without deploying to a cloud environment (deploying locally)
• You are deploying to a Private Cloud or On-Premises, rather than the Mendix Cloud

In these cases, you can still publish and consume external entities. This guide will explain how to work with the Catalog and external entities by taking a step back and distinguishing between design time (when you are modeling your app) and runtime (after it has been deployed to a development server).

2 Using Data in Design Time

During design time, when you are modeling your app, you are finding, registering, or importing data source metadata into Studio Pro. This metadata is in the form of contracts, and is registered automatically in the Catalog if your application is hosted on the Mendix Cloud. See the Metadata Contracts section below for more details.

If you will be deploying locally, to a Private Cloud, or On-Premises, you can add an app, the environments on which it is deployed, and the published OData entity it provides using the metadata contract. For general resources on using data when modeling your app during design time, check out Share Data Between Apps and Write Data to Another App.

2.1 Metadata Contracts

The Catalog acts as a phonebook or map to the data and capabilities provided by software in your organization. It contains metadata about the applications, environments, services, and versions deployed. For every system registered, the contracts describing its services are parsed and stored, so users can easily find the descriptions of the datasets, logic, and events provided by these systems. The Catalog does not contain any data, only the metadata required to describe these applications and services.

See the Registering a Service Through the Mendix Cloud section of *Register OData Resources in the Catalog to read how this works if you are deploying to the Mendix Cloud.

2.1.1 Supported Metadata Contract Types

We support ZIP (for multiple file contracts) or XML (for single file contracts).

2.2 Manually Registering Contracts to the Catalog with Team Server

If you deploy to a Private Cloud or On-Premises setup, and use the Mendix Team Server, you can manually register applications, environments, services, or data sources to the Catalog. Registering the data source contracts to the Catalog ensures that it can be found and imported into an application by members of the company that owns it.

To manually register an OData contract metadata file to the Catalog, follow these basic steps:

1. Create an .mda package to deploy. To do this, go to the Environments page in the Developer Portal and click Create Package From Teamserver. The .mda package contains a dependencies.json file that lists all published and consumed OData services.
2. Use the Transform operation to transform the contents of dependencies.json into payloads for other operations (see the Transform operation specs).
3. Use the Registration API to register the data source.

For detailed steps, see the Registering a Service without the Mendix Cloud section of Register OData Resources in the Catalog.

2.3 Manually Registering Contracts to the Catalog without Team Server

To manually register contracts to the Catalog without the Mendix Team Server, do the following:

1. Export the contract from the publishing app and download it to your computer.
   Go to Settings tab of the Published OData Service document, and click Export next to the Metadata field. Save the $metadata.xml file.
2. Register the contract into the Catalog manually.
   See the Registering a Service without the Mendix Cloud section of Register OData Resources in the Catalog.

2.4 Importing Contracts Directly into Studio Pro (Bypassing the Catalog)

If you are deploying locally, or do not want to register the data sources in the Catalog, you can import the metadata contracts or service URLs directly into Studio Pro to consume a published OData service.

2.4.1 Importing from a File

To import a metadata contract file of a published OData service, do the following:

1. Export the contract from the publishing app and download it to your computer.

   Go to Settings tab of the Published OData Service document, and click Export next to the Metadata field. Save the $metadata.xml file.

2. Import the contract into the consuming app.

   Right-click the App Explorer where you would like to add the service, then click Add other > Consumed OData Service. Select the $metadata.xml file you exported.

The service will now appear in the Integration pane.

2.4.2 Importing from a URL

To import a published OData service URL, do the following:

1. Copy the OData service URL.

   To find the published OData service URL from Mendix apps, go to the Settings tab of the Published OData Service document, and copy the entire link in the Metadata field.

2. Add a Consumed OData service to your consuming app.

   Right-click the App Explorer in the module where you would like to add the service, then click Add other > Consumed OData Service.

3. In the Add Consumed OData Service dialog box, make sure From URL is selected, and paste the copied URL into the field.

The service will now appear in the Integration pane.

2.5 Updating a Manually Registered Contract

To update the metadata of a manually registered contract, follow the same steps as an initial registration. Then, indicate during the registration that the updated source is a new version in an existing environment of an existing app.

To update a data set in Studio Pro, do the following:

1. Open your app and the published OData service you want to update.
2. Under Entities, select Customer, and click Edit.
3. Select the checkbox for Updateable and click OK.
4. Click Publish.

See the Update or Switch section of Consumed OData Service to see how this works for automatically registered contracts.

3 Using Data in Runtime

During runtime, after you have deployed your app to a development server, the exchange of external entities via OData services occurs between publishing and consuming apps. Anyone who deploys to a Private Cloud or On-Premises can consume the OData resources that are set up when using data in design time. The Catalog is not involved during runtime.