51Degrees API Documentation  4.5

Documentation

• Pipeline API
• API features
• Derived properties

Derived properties

Introduction🔗

The derived property element works out new properties from properties that other elements in the Pipeline have already produced. It follows rules written in a short script, in YAML or JSON, with one script for each property it produces.

The element holds no data file, sends no request over the network and needs no Resource Key or License Key. It reads no evidence from the request either. Everything it reads is a property another element has already written into the flow data, so it goes in the Pipeline after those elements.

A script is for a property that follows simply from properties already in the flow data, such as putting a number into bands or combining two flags into one answer. Work that needs a network call, needs to keep something between requests, or needs the raw evidence (headers, query string or cookies) belongs in an element of your own instead, as Custom flow elements describes.

See the Specification for more technical details, and the script format reference for everything a script can say.

The properties it gives🔗

Each script writes one property, named by the script, into the element data under the key derived. A script that produces HumanConfidence is read as derived.HumanConfidence, and the cloud's JSON gives it as derived.humanconfidence.

The packages carry the scripts in the derived-properties repository, which you can add by name.

Property	Values	Engines to add	Script
HumanConfidence	High, Medium, Low or Unknown	Device Detection and IP Intelligence	HumanConfidence.yaml
IsGdpr	True or False	IP Intelligence	IsGdpr.yaml

HumanConfidence is described on Human Confidence overview. IsGdpr is defined by its script as "Whether the General Data Protection Regulation, or the United Kingdom's version of it, is likely to apply to the person making the request, judged from the country of the supplied location", and its script says that it is a default for a caller that knows nothing about its own position, and not a determination.

A script below version 1.0.0 is a draft and may change. Both of these are below 1.0.0 today.

Each script names every property it reads, so the elements that supply them have to be in the Pipeline, and the properties have to be in your data files or your Resource Key. Where one is missing, the property has no value and says why, as the next section describes.

Scripts of your own🔗

You can write a script for a property of your own. The authoring guide works through one from a blank file, and the script tester runs a script in a browser against values you type, showing which rule matched.

When a property has no value🔗

Where every property a script reads is available, the script's rules run and it gives a value. Where any one of them is not available, the property has no value, and its message names every property that could not be read and what the element that supplies it said. For IsGdpr, which reads the country code ip.CountryCode, the message has this shape.

Derived property 'IsGdpr' has no value because 1 source property was not available. 'ip.CountryCode' (element 'ip' has no value for 'CountryCode': ...). Usual causes are the element that supplies the property not being in the pipeline, the property being excluded in the engine configuration, the property not being included in the resource key, or JavaScript that populates the property not having run yet.

Where more than one property is not available, the count reads <n> source properties were not available and each property is named in turn.

There is no third state. A value that cannot be read as the type the script expects counts as not available, so a value such as Unknown or N/A never turns into false or zero.

When the Pipeline is built🔗

Building the element checks every script and reports every fault in one message, rather than stopping at the first one. Each fault names the script, where it came from, the place in the document and what is wrong.

Building the Pipeline then fails, naming the property, when no element in the Pipeline supplies a property a script reads, or when two derived property elements write a property of the same name. Where the elements sit is not checked, so the Aspect Engines that supply the properties can run in a parallel group ahead of the derived property element.

Configuration🔗

A script reaches the element in one of three ways, and one element can take all three.

1. By name, for a script the package carries.
2. From a file in your own environment, where a path can hold a wildcard such as derived/*.yaml.
3. As text held by your own code, in YAML or JSON. This one is available in code only.

In a configuration file, Scripts names the scripts the package carries and ScriptFiles gives the paths of your own. Write each as one string with commas between the entries, not as a JSON array.

{

"PipelineOptions": {

"Elements": [

{

"BuilderName": "DerivedPropertyElement",

"BuildParameters": {

"Scripts": "HumanConfidence",

"ScriptFiles": "derived/*.yaml"

}

}

]

}

}

In PHP the builder name is the class's full name, written in JSON as "BuilderName": "fiftyone\\pipeline\\derivedproperty\\DerivedPropertyElement", the way other PHP elements are named on Building from configuration.

In Go, register derivedproperty.NewFromConfiguration with a core.BuilderRegistry under derivedproperty.BuilderName, then build the Pipeline with the registry's BuildFromConfiguration.

Using it🔗

C# Go PHP Rust

Select a language.

Add the FiftyOne.Pipeline.DerivedProperty package from NuGet. The source is in pipeline/DerivedProperty, and the DerivedProperty example runs with no data file, key or network, building the element both from a configuration file and in code, and showing a property with no value.

var derived = new DerivedPropertyElementBuilder(loggerFactory)

// A script the package carries.

.AddScript(BuiltInScript.HumanConfidence)

// A file, or every file a wildcard matches.

.AddScriptFile("derived/*.yaml")

// The text of a script held by your own code, YAML or JSON.

.AddScript("MyProperty", scriptText)

.Build();

// Add the element after the engines that supply what its scripts read.

var pipeline = new PipelineBuilder(loggerFactory)

.AddFlowElement(deviceDetectionEngine)

.AddFlowElement(ipIntelligenceEngine)

.AddFlowElement(derived)

.Build();

using (var flowData = pipeline.CreateFlowData())

{

flowData.AddEvidence("header.user-agent", userAgent)

.AddEvidence("server.client-ip", clientIp)

.Process();

var confidence = flowData

.Get<IDerivedPropertyData>()

.GetAs<IAspectPropertyValue<string>>("HumanConfidence");

Console.WriteLine(confidence.HasValue ?

confidence.Value :

confidence.NoValueMessage);

}

Add the pipeline module with go get github.com/51Degrees/51degrees-go/pipeline/v4. The element is its elements/derivedproperty package, in pipeline/elements/derivedproperty. The Go on-premise engines do not run in a Pipeline yet and Go has no Device Detection cloud engine, so a script that reads device properties, such as HumanConfidence, needs them from an element of your own. IsGdpr runs with the IP Intelligence cloud engine, as below. The derived property example shows a script held in the code, a script read from a file, the same Pipeline built from a configuration file, and a property with no value.

import (

"fmt"

"log"

"github.com/51Degrees/51degrees-go/ip-intelligence/v4/ipi_cloud"

"github.com/51Degrees/51degrees-go/pipeline/v4/cloud/requestengine"

"github.com/51Degrees/51degrees-go/pipeline/v4/core"

"github.com/51Degrees/51degrees-go/pipeline/v4/elements/derivedproperty"

"github.com/51Degrees/51degrees-go/pipeline/v4/engines"

)

derived, err := derivedproperty.NewBuilder().

// A script the package carries.

AddBuiltInScript(derivedproperty.IsGdpr).

// A file, or every file a wildcard matches.

AddScriptFile("derived/*.yaml").

// The text of a script held by your own code, YAML or JSON.

AddScript("MyProperty", scriptText).

Build()

if err != nil {

// Lists every fault in every script.

log.Fatal(err)

}

requestEngine, err := requestengine.NewBuilder().

SetResourceKey(resourceKey).

Build()

// Add the element after the engines that supply what its scripts read.

pipeline, err := core.NewPipelineBuilder().

AddFlowElement(requestEngine).

AddFlowElement(ipi_cloud.New(nil)).

AddFlowElement(derived).

Build()

defer pipeline.Close()

fd := pipeline.CreateFlowData()

fd.AddEvidence("query.client-ip", clientIP)

err = fd.Process()

data, err := core.Get[*derivedproperty.Data](fd)

isGdpr, err := derivedproperty.GetAs[engines.AspectPropertyValue[bool]](

data, "IsGdpr")

if value, err := isGdpr.Value(); err == nil {

fmt.Println(value)

} else {

// Names every property that could not be read, and why.

fmt.Println(isGdpr.NoValueMessage())

}

The 51degrees/fiftyone.pipeline.derivedproperty package is not on Packagist yet, so use it from a clone of the 51degrees-php repository through a Composer path repository. The source and its readme are in pipeline/derivedproperty.

use fiftyone\pipeline\core\PipelineBuilder;

use fiftyone\pipeline\derivedproperty\DerivedPropertyElementBuilder;

$derived = (new DerivedPropertyElementBuilder())

// A script the package carries.

->addBuiltInScript('HumanConfidence')

// A file, or every file a wildcard in the file name matches.

->addScriptFile('derived/*.yaml')

// The text of a script held by your own code, YAML or JSON.

->addScript('MyProperty', $scriptText)

->build();

// Add the element after the engines that supply what its scripts read.

$pipeline = (new PipelineBuilder())

->add($cloudRequestEngine)

->add($deviceDetectionCloud)

->add($ipIntelligenceCloud)

->add($derived)

->build();

$flowData = $pipeline->createFlowData();

$flowData->evidence->setFromWebRequest();

$flowData->process();

$humanConfidence = $flowData->derived->humanconfidence;

echo $humanConfidence->hasValue ?

$humanConfidence->value :

$humanConfidence->noValueMessage;

Add the fiftyone-derived-properties crate from crates.io. The source and its readme are in derived-properties. The scripts are compiled into the crate, so the element runs where there is no file system, such as in WebAssembly. The derived-property example shows a script held in the code, a script read from a file, the same Pipeline built from an options file, and a property with no value.

use std::sync::Arc;

use fiftyone_derived_properties::{BuiltInScript, DerivedPropertyElement};

use fiftyone_pipeline_core::Pipeline;

let derived = DerivedPropertyElement::builder()

// A script the crate carries.

.add_built_in(BuiltInScript::HumanConfidence)

// The text of a script held by your own code, YAML or JSON.

.add_script("MyProperty", my_script_text)

// A file, or every file a wildcard matches.

.add_script_file("derived/*.yaml")

.build()?;

// Add the element after the engines that supply what its scripts read.

let pipeline = Pipeline::builder()

.add_element(device_detection)

.add_element(ip_intelligence)

.add_element(Arc::new(derived))

.build()?;

let mut data = pipeline.create_flow_data_with(evidence);

data.process()?;

match data.get_str("derived").unwrap().get("HumanConfidence") {

Ok(value) => println!("{value:?}"),

// Names every property that could not be read, and why.

Err(no_value) => println!("{}", no_value.message),

}

The feature matrix shows which languages have the element.

The cloud🔗

The 51Degrees cloud gives a derived property by running this same element in its own Pipeline, so a cloud answer and an answer from your own servers come from the same script. Choose the property for your Resource Key like any other. Where a property a script reads was not available, the cloud gives the property as null with the reason alongside it, for example humanconfidencenullreason.

Example🔗

.NET

Have a data or code question? Get in touch and explore subscription options.