![No UI](https://img.shields.io/static/v1?label=UI&message=none&color=inactive)

This extension allows you to consume _Public URLs_ on the conversion server - why re-convert the same image over and over again, when you have that derivative already on your CDN.

Another use case for this is when CELUM only has a dummy file as the asset, and the real binary is stored somewhere else, e.g. for some 3dr party system integration.

[MINITOC]

## Properties

To be configured in {home}/appserver/conf/custom.properties

##### publicUrlDownloadTranslator.license

> type: string, required: **yes**, default: -

The license key for the plugin (product: publicUrlDownloadTranslator), provided by *brix*.

##### publicUrlDownloadTranslator.publicUrlKeyDelimiter

> type: string, required: no, default: ```:```

The delimiter used to split the three identifying parts (provider:instance:description) of a Public URL key. Usually the description is enough though.

##### publicUrlDownloadTranslator.staticFallbackUrl

> type: string, required: no, default: -

A static URL that will be delivered in case there's no matching Public URL on an asset, so you can deliver an "error" image instead. **This is probably not what you want**, as the conversion process can be configured to fall back to a regular conversion.

## Setup

Since this is an addition to the conversion process, you're gonna have to mess with your ```home/appserver/spring/conversionProcessDefinitions.xml```. Adapt it as follows:

#### 1. Modify the DownloadImage process to fall back on

In order to use the existing DownloadImage process (so you don't have to write all of what it does in the new process), the following two modifications are necessary:

Add an ```id``` to the outermost bean, so it can be referenced (to inherit the supported extensions and configuration parameters) - e.g. ```id="downloadImageProcess"```:

```xml
<!--   ***********************************************************************
*                _____          DownloadImage              _____                *
************************************************************************   -->
<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDefinition" id="downloadImageProcess">
```

Extract the ```processStepList``` property (so it can be referenced from both processes) and use ```ref="downloadImageProcessStepList"``` instead.

*Before:*

```xml
<!--   ***********************************************************************
*                _____          DownloadImage              _____                *
************************************************************************   -->
<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDefinition">
  <!-- snip (supportedExtensions, parameterList reside here) -->
  <property name="processStepList">
    <list>
      <!-- snip (all the conversion steps reside here) -->
    </list>
  </property>
</bean>
```

*After:*

```xml
  <!--   ***********************************************************************
*                _____          DownloadImage              _____                *
************************************************************************   -->
<bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDefinition" id="downloadImageProcess">
  <!-- snip (supportedExtensions, parameterList reside here) -->
  <property name="processStepList" ref="downloadImageProcessStepList" />
</bean>

<util:list id="downloadImageProcessStepList">
  <!-- snip (all the conversion steps reside here) -->
</util:list>
```

#### 2. Add the new download tool

In ```home/conversionserver/conf/environment.conf```, add wget:

```ini
# wget downloader
commandLineTool.wget.executable=/usr/bin/wget
commandLineTool.wget.monitorProgress=false
commandLineTool.wget.validateExecutionCommandLine=--version
commandLineTool.wget.expectedValidationOutput=GNU Wget 1\\.[0-9]+
```

For Windows: download wget.exe [here](https://eternallybored.org/misc/wget/) and either specify the full path for the executable or add it to the Windows/System32 folder (then it is enough to set commandLineTool.wget.executable=wget).

Restart the conversionserver.

#### 3. Add the new download process

```xml
  <!--   ***********************************************************************
  *                _____          DownloadPublicUrl              _____                *
  ************************************************************************   -->
  <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDefinition" parent="downloadImageProcess">
    <property name="name" value="DownloadPublicUrl"/>
    <property name="parameterList">
        <list merge="true"><!-- add one additional parameter to the inherited parameterList) -->
          <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDefinitionParameter">
              <property name="identifier" value="publicUrlKey"/>
              <property name="description" value="Key of the PublicURL to fetch. Passing the 'description' is enough, but it can be refined with 'provider:description' or 'provider:instance:description'"/>
              <property name="label" value="PublicURL Key"/>
          </bean>
      </list>
    </property>

    <property name="processStepList">
      <list>
        <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStep">
          <property name="conversionProcessExecutorName" value="variable-modification"/>
          <property name="parameters">
            <set>
              <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                <property name="parameterName" value="TargetVariable"/>
                <property name="parameterValue" value="hasPublicUrl"/>
              </bean>
              <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                <property name="parameterName" value="Expression"/>
                <property name="parameterValue" value="$translator[HasPublicUrlDownloadTranslator:$option[publicUrlKey]]"/>
              </bean>
            </set>
          </property>
        </bean>
        <!-- the reason this has to exist is because there's no "VariableDefined", so we could check if the URL was empty -->
        <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDecision">
          <property name="conversionProcessExecutorName" value="option-decision"/>
          <property name="parameters">
                <set>
                    <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                        <property name="parameterName" value="VariableValue"/>
                        <property name="parameterValue" value="hasPublicUrl"/>
                    </bean>
                </set>
          </property>
          <property name="branches">
                <list>
                    <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDecisionBranch">
                        <property name="branchName" value="true"/>
                        <property name="processStepList">
                            <list>
                              <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStep">
                                  <property name="conversionProcessExecutorName" value="commandLine"/>
                                  <property name="parameters">
                                      <set>
                                          <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                                              <property name="parameterName" value="ToolName"/>
                                              <property name="parameterValue" value="wget"/>
                                          </bean>
                                          <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                                              <property name="parameterName" value="CommandLine"/>
                                              <property name="parameterValue"
                                                        value="-q -O download.$option[imageFormat] '$translator[PublicUrlDownloadTranslator:$option[publicUrlKey]]'"/>
                                          </bean>
                                      </set>
                                  </property>
                              </bean>
                              <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStep">
                                  <property name="conversionProcessExecutorName" value="dataTransfer"/>
                                  <property name="parameters">
                                      <set>
                                          <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                                              <property name="parameterName" value="TransferMode"/>
                                              <property name="parameterValue" value="download"/>
                                          </bean>
                                          <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessStepParameter">
                                              <property name="parameterName" value="RemoteFileRef"/>
                                              <property name="parameterValue" value="download"/>
                                          </bean>
                                      </set>
                                  </property>
                              </bean>
                            </list>
                        </property>
                    </bean>
                    <bean class="com.celum.imagine.conversion.processing.definition.ConversionProcessDecisionBranch">
                        <property name="branchName" value="false"/>
                        <property name="processStepList" ref="downloadImageProcessStepList" />
                    </bean>
                </list>
          </property>
        </bean>
      </list>
    </property>
  </bean>
```

Restart the appserver - you can now select the new ```DownloadPublicUrl``` process in the CMA:

![Public URL for Conversions settings in the CMA](CMA_download_public_url.png  "Public URL for Conversions settings in the CMA")

## Compatibility Matrix

| publicUrlDownloadTranslator | CELUM (min. version)       |
|:--------------------------- |:-------------------------- |
| 1.0                         | 5.13.4 (tested up to 6.16) |

## Release Notes

#### 1.0

> Released 2019-08-16

Initial version

#### 1.1

> Released 2019-08-17

Added support for staticFallbackUrl

#### 1.2

> Released 2021-01-06

Added license check