Managing Exchange Policies

At least one Exchange policy must be configured using the administration interface to use 1Exchange and the 1Spatial Management Suite, however multiple policies can be configured.

The 1Exchange administration interface is accessed from: http://[machine]:[port]/1exchange/admin

Note: The port number is defined during installation, but by default this is set to 7115.

There are two different Exchange Policy types available:

  • Snowflake
  • FME Server

1Workflow administrators can configure which Exchange policy to use for each job type, via the Workflow admin page.

Creating an Exchange Policy

ClosedCreate an Exchange Policy

  1. Navigate to the 1Exchange Administration interface.

  2. Click and enter a name in the Policy Name field.

    Click to confirm the policy name.

  3. Enter the policy details (see Snowflake Exchange Policy Parameters or FME Exchange Policy Parameters).

  4. Click to save the policy.

ClosedSnowflake Exchange Policy Parameters

ClosedFME Exchange policy Parameters

Updating or Deleting an Exchange Policy

To update an Exchange policy, select an existing policy and modify the parameters as required (see Snowflake Exchange Policy Parameters).

To confirm your changes, click .

Note: If you navigate away from the current policy (for example, by selecting another Exchange policy), you must confirm whether or not you want to discard or save your changes.

To delete an Exchange policy, select an existing Exchange policy, click and confirm the deletion when prompted.

Copying an Exchange Policy

To copy an Exchange policy, select an existing policy and click .

The name for the new Exchange policy is displayed. A default name consisting of a prefix Copy_of_ and the name of the original Exchange policy is given.

With the exception of its name, the new policy will have the same attribute values as the original policy.

Applying Adaptors to an Exchange Policy (GO Loader and GO Publisher)

An exchange policy can optionally specify Extraction and/or Submission adaptors. These will be applied to the data after each extraction and before each submission.

To use an Extraction Adaptor, select Use Extraction Adaptor. This is carried out within the 1Exchange Admin Policy configuration window.

One an Adaptor type has been selected, a list of available adaptors is displayed; by default this is the FME adaptor.

Select an adaptor from the list and the list of input parameters is displayed. In the case of the FME Adaptor, these are:

Parameter Description Typical Value
FME Url The location of the FME server https://<machine>:<port>
FME username The username for the FME server pointed to by FME Url N/a
FME password The password for the FME server pointed to by FME Url N/a
Workspace name The name of the extraction/submission workspace. Including containing repository (e.g. [repository]/[extraction_workspace]).
Overwrite features

If selected, the features.zip in the job package will be replaced by the file returned from FME Server.

If left un-checked, then the features.zip remains unchanged, with the file returned from FME Server packaged as adapted_features.zip.

Note: This option will only appear on Extraction Adaptors.

Boolean

 

To use a Submission Adaptor, select Use Submission Adaptor, also located within the 1Exchange Admin Policy configuration window. A list of available adaptors is displayed.

Select an adaptor from the list and the list of input parameters is displayed.

If you are using the FME Adaptor, the list of parameters is the same as above, but the workspace will differ to the extraction workspace as it will be performing the reverse translation.

Additional adaptors can be added to 1Exchange as REST services. By default, 1Exchange includes a FME Server adaptor but other software can be used for converting data by implementing the REST service to invoke that software.

ClosedSetting up an FME Workspace for use as an Adaptor

Note: Ensure that any translated files end up in the root directory of the zip created by the Data Download service.

There are number of requirements on the FME Workspace that are needed in order for an exchange adaptor to work.

1Exchange will call FME Server to run the Workspace and will provide a number of parameters:

Extraction FME Workspace Published Parameters

Parameter Type Required Description
Extraction_File Filename (Multiple) Required The GML 3.2.1 features file.
Job_Metadata_File Filename (Multiple) Required An XML file containing the job metadata
Validation_Report_File Filename (Multiple) Optional A validation report generated by 1Validate or 1Integrate. Only supplied for child jobs, or where pre-validation is carried out.

The job metadata file and validation report can be ignored, or can be processed in the workspace as required.

The extraction workspace should carry out any required translation on the supplied GML 3.2.1 file and needs to output to a file which is returned to 1Exchange by FME Server. 1Exchange will package up the returned file into adapted_features.zip.

Submission FME Workspace Published Parameters

Parameter Type Required Description
Updates_File Filename (Multiple) Required The edited file which the user uploaded through the Worklist.
Extraction_File Filename (Multiple) Required The original GML 3.2.1 features file.

The submission workspace should carry out any required translations on the updates file to make it schema compatible with the original GML 3.2.1. It should then compare Updates_File to Extraction_File to determine the changes and then generate a GML change only file which is returned to 1Exchange.

Both the submission and extraction workspace must be published to FME Server with services: Data Download and Job Submitter.

ClosedAdd an Adaptor Implementation

  1. Add an entry in the adaptors.properties file in the form [adaptor-label]=[adaptor-url].

    For example, for the FME adaptor the entry is:

    FME\ Adaptor=http://localhost:7115/adaptor/fme/rest/fme_adaptor

  2. Define the REST service implementation.

    The API is:

    public interface ExchangeAdaptorRestService

    {

    @GET

    @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })

    Capabilities getCapabilities();

     

    @GET

    @Path("/{processId}")

    @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })

    AdaptorProcess describeProcess(@PathParam("processId") String processId);

     

    @POST

    @Path("/{processId}")

    @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })

    @Consumes(MediaType.MULTIPART_FORM_DATA)

    Response execute(@PathParam("processId") String processId, @Context HttpServletRequest request) throws Exception;

    }

    Where:

    • getCapabilities - returns a Capabilities object that represents List<AdaptorProcesses>
    • describeProcess(processId) - returns an AdaptorProcess, that contains the following information:
    • id - unique ID to identify the process in this adaptor
    • description - description of the process
    • inputs - list of input parameters
    • output - output parameter of the process
    • execute(processId, request) - indicates the process to execute using the parameters in the request

    As an example, for the FME adapter the process is:

    id fme_adaptor
    description Converts data using an FME workspace
    inputs FME server URL, user name and password, workspace name
    output Currently unused, but could be the name of adapted file inside features.zip on extraction

All adaptors also have fixed inputs that do not need to be specified. These are:

  • Extraction adaptor - file containing the extracted GML 3.2.1 data to be converted.

    For the FME adaptor provided, this is a published parameter of the workspace with name Extraction_file.

  • Submission adaptor - A file containing the original data after it was converted by the Extraction adaptor and a file containing the feature updates.

    If the feature updates are provided in a change-only format then the adaptor only needs to convert the updates file to GML 3.2.1. If the feature updates are provided as a full file including the changes, the adaptor can compare against the original file to detect the changes and create a change-only GML file.

    For the FME adaptor provided, this is a published parameter of the workspace with name Updates_file.

Policy Metadata

To see all metadata for an Exchange policy, select the policy. A panel is displayed on the right-hand side showing the following attributes of the Exchange policy:

ClosedFME Exchange Policy metadata

  • Name - Name for the Exchange policy
  • Path - URL for the Exchange policy
  • Created by - User who created the Exchange policy
  • Created date - Timestamp when the Exchange policy was created
  • Policy buffer - Distance by which to buffer the extraction window
  • Policy srs_name - Default SRS for the Exchange policy
  • Policy grow_extents_list
  • Policy grow_extents_buffer
  • Policy fme_url
  • Policy fme_username
  • Policy fme_password
  • Policy fme_extraction_workbench
  • Policy fme_submission_workbench

ClosedSnowflake Exchange Policy Metadata

  • Name - Name for the Exchange policy
  • Path - URL for the Exchange policy
  • Created by - User who created the Exchange policy
  • Created date - Timestamp when the Exchange policy was created
  • Policy go_publisher_project - Name of the GoPublisher product
  • Policy go_loader_project - Name of the GoLoader product
  • Policy buffer - Distance by which to buffer the extraction window
  • Policy srs_name - Default SRS for the Exchange policy

Some attributes are configurable, however others (such as the creation user name and timestamps) are assigned by the system.

To hide the metadata panel, click . To display the metadata, re-select the Exchange policy.

Grow Extents

1Workflow can automatically grow the extent of a job. This is useful to ensure that enough data is extracted to allow all the features that are wholly or partially within the original area of interest to be safely edited and validated.

Often, validation rules require all the features that surround a feature to be available to perform the validation. To guarantee that a feature can be edited and validated, administrators usually require that jobs are automatically expanded to include all the features that surround those that are partially within the original area of interest. To achieve this, 1Workflow asks 1Exchange to query the base data for features to use to grow the job extent, and then adds a buffer to the result.

1Workflow contains a setting to indicate whether or not the original job extents should be grown automatically.

Note: Activating a job takes slightly longer if job extents are being grown.

For each Exchange policy, an administrator can define how the job extent should be grown. The Exchange policy in the administration page contains the following fields:

  • Grow Extents Buffer (mandatory) - Real with default value of 0.1, expressed in meters.

    If a value is entered with a value lower than 0.1, it will automatically be set back to 0.1.

    A buffer is always applied when growing extents. If no geometry columns are specified below, only the buffer will be applied to the original geometry.

  • Grow Extents Geometries (optional) - Comma separated list of geometry columns that are queried to find intersecting features to use to grow the job extent before buffering it.

    The format of this setting is [table_name].[geometry_name], for example LAND.GEOMETRY.WATER.POLY_GEOM.

    Any geometries (points or lines) from these geometry columns that intersect the boundary of the original job extent are used to grow the job extent to ensure enough data is available for editing and validation. Any holes in the resulting enlarged job extent are removed to ensure complete data.

Note: 1Plan and 1Edit will continue to display the original unexpanded area of interest (as this defines where the edits should be happening), however the enlarged extent is used when extracting data and identifying the data to use for validation.

Additional extraction rules are applied by 1Exchange as normal after identifying the initial set of target features using the enlarged extent (rules such as including additional features that are referenced by those within the extraction extent).