Metric descriptions

Hello everybody,

I have some Metrics that need a long description.

What are the options available?

ES (Python):

“description”: ("very long string 1° part "
“- very long string 2° part”)

result:
very long string 1° part - very long string 2° part

Do we have \n, \t etc.?

ES:
“description”: ("- First\n- Second")

result:

  • First
  • Second

Thanks,
Mario

The field Metric.description is a long string field that is defined as:

description: long string translate by name

Which means that the value for this field comes from the Translation type.

Translation.value is also a long string (max 4000 characters), so you can use that field for your long description. Yes, \n and \t should be supported.

See the “Translations” documentation article for more information on how to setup translations for data.

Hi Matt,

Thanks for your answer.

I looked at the documentation for the type “Translation” (using c3ShowType) but it didn’t help, this is all the description that I see for “value”:

value: string

Declaration

@typesys(allowVoid=true) value: long string

Maybe you where referring to another article? can you link it?

I still don’t understand how can I write a very long description using more than one line. To be clear this is just to avoid to have a very long line in the .js file. For example in Python PEP8 suggest to limit the length of each line to 79 character (72 for docstring), I know that in C3 generally there is no limit but still I would like to avoid to write a very long string using just one line.

In Python for doc strings one can use
“”“This is
a very long
docstring.
“””
I’m searching for something similar here.

Here

I see that they use this format:

     "result" : "this is a very long line which is not easily readble. \
                  so i would like to write it in multiple lines. \
                  but, i do NOT require any new lines in the output."

I’ll try to see if it works, in any case suggestions are welcome.

Thank you,
Mario

I’m referring to the documentation article called “Translations”. You can view the documentation site by going to Help > Documentation from the C3 Console and then search for “Translations”.

Thanks Matt,

I did what you suggested but I don’t see any info related to my question in that page.

In C3 when you write a description for a metric you always write it in one line or you have a way to write it in more than one line when its very long?

For example:

“description”: “The value of this metric it’s 1 when there is a consumption of active energy that starts and ends in a period where the service was supposed to be inactive, it’s 0 otherwise.”

How can I write this in more than one line?

Best,
Mario

When we write descriptions for metrics, we create a Translation seed data object like this:

<package>/seed/Translation/en.json:

[
  {
    "id": "en.data.SimpleMetric.MyMetric.description",
    "locale": "en",
    "key": "data.SimpleMetric.MyMetric.description",
    "value": "This is the metric description."
  }
]

That way, when we fetch SimpleMetric objects:

SimpleMetric.fetch({ include: 'description' })

The result contains the description from the Translation seed data.

{
  "objs": [
    {
      "id": "MyMetric",
      "description": "This is the metric description."
    }
  ]
}

As for authoring the seed data, you can include newlines in the Translation data by writing the JSON like this:

[
  {
    "id": "en.data.SimpleMetric.MyMetric.description",
    "locale": "en",
    "key": "data.SimpleMetric.MyMetric.description",
    "value": "Description line 1
Description line 2
Description line 3"
  }
]

Which will result in the following fetch result:

{
  "objs": [
    {
      "id": "MyMetric",
      "description": "Description line 1\nDescription line 2\nDescription line 3"
    }
  ]
}

Thanks Matt!

I wrote my description directly in the metric definition, like this:

{
“srcType”: “soruceType”,
“id”: “metricName_soruceType” ,
“name”: “metricName”,
“tsDecl”: { something},
“description”: “Long description of the metric.”
}

What is the utility of this description field if to have a description I have to write it also in the en.json (inside the field “value”)?

I imagine that for a Compound its just the same,

[
{
“id”: “en.data.CompoundMetric.MyCompoundMetric.description”,
“locale”: “en”,
“key”: “data.CompoundMetric.MyCompoundMetric.description”,
“value”: “Description line 1
Description line 2
Description line 3”
},
{
“id”: “en.data.SimpleMetric.MySimpleMetric.description”,
“locale”: “en”,
“key”: “data.SimpleMetric.MySimpleMetric.description”,
“value”: “Description line 1
Description line 2
Description line 3”
}
]

Thanks,
Mario

A description included in the metric definition file (.json) is useful only for people that have access to the source code. Since the description field is a translated field, descriptions provided in this way never make it to the database, so it’s not possible to surface it to users of your application. Currently, the platform does not raise an “extraneous field” error/warning when provisioning this kind of data, but that could potentially change in the future, since this behavior could be confusing.

But if you want descriptions only for internal documentation purposes, go ahead and put it directly in the metric definition for now.


Correct!

Hi Matt!

Thanks for your answer, now is clear.

As a personal opinion, I don’t like the fact that I have to write the description in a separate file instead of where I define the metric, I would find a lot better to write it in the field “description” of the metric.

The whole Translation folder if one doesn’t want to do fancy stuff is just an additional “complexity” (it can be generated automatically one time you have a field description in the metric definition).

But this is just my opinion,

Best,
Mario

Hi All,

if you want, like me, put your metric description in the field description of the metric or if you just want to migrate all your descriptions in Translation/en.json I wrote a simple python script for this:

import glob
import os

os.makedirs("seed/Translation", exist_ok=True)

template = """    {{
        "id": "en.data.{folder}.{metric_name}.description",
        "locale": "en",
        "key": "en.data.{folder}.{metric_name}.description",
        "value": "{description}"
    }},
"""

en = "[\n"

for folder in ["SimpleMetric", "CompoundMetric"]:
    for path in glob.glob("seed/{}/*".format(folder)):
        metric_name = path[:-5].split(os.sep)[1].split('_')[0]
        with open(path, 'r') as f:
            description = eval(f.read().replace('\n', ''))
            if "description" in description.keys():
                description = description["description"]
            else:
                continue
        en += template.format(folder=folder, metric_name=metric_name, description=description)

en = en[:-2] + "\n]\n"

with open("seed/Translation/en.json", "w") as f:
    f.write(en)

Best,
Mario

Hi @matt, the documentation that before was displayed after the migration to 7.9 doesn’t show up any more.

If I do
c3Grid(SimpleMetric.fetch({include: “[description]”}))

I see as description the metric name but I have an en.json in the Translation folder (that was OK until 7.9).

My en.json is like this (with more metrics):

 [
    {
        "id": "en.data.SimpleMetric.ChInRevproMeActiveEnergyEndPeriod.description",
        "locale": "en",
        "key": "en.data.SimpleMetric.ChInRevproMeActiveEnergyEndPeriod.description",
        "value": "The value of this metric it's 1 at the end of the period to which a billed active energy consumption refers, it's null otherwise."
    },
    {
        "id": "en.data.SimpleMetric.ChInRevproMeActiveEnergyStartPeriod.description",
        "locale": "en",
        "key": "en.data.SimpleMetric.ChInRevproMeActiveEnergyStartPeriod.description",
        "value": "The value of this metric it's 1 at the start of the period to which a billed active energy consumption refers, it's null otherwise."
    }
]

Best,
Mario

Hi @mnslarcher,

The Translation key should start with data.. From the Translations documentation article:

The key of the Translation must follow the convention data.<Type name>.<object id>.<field name> .

Hi matt, thanks for your answer. I thought to have check that the description was OK also after running the script that I posted above but apparently I had checked only after manually trying to add description s in Translation.

Now I tested also after the en.json generation, the correct script is this (I’m sharing it just if someone need to move the descriptions from the metrics field to the en.json like me):

import glob
import os

os.makedirs("seed/Translation", exist_ok=True)

template = """    {{
        "id": "en.data.{folder}.{metric_name}.description",
        "locale": "en",
        "key": "data.{folder}.{metric_name}.description",
        "value": "{description}"
    }},
"""

en = "[\n"

for folder in ["SimpleMetric", "CompoundMetric"]:
    for path in glob.glob("seed/{}/*".format(folder)):
        metric_name = path[:-5].split(os.sep)[1].split('_')[0]
        with open(path, 'r') as f:
            description = eval(f.read().replace('\n', ''))
            if "description" in description.keys():
                description = description["description"]
            else:
                continue
        en += template.format(folder=folder, metric_name=metric_name, description=description)

en = en[:-2] + "\n]\n"

with open("seed/Translation/en.json", "w") as f:
    f.write(en)

This script now work as expected, all the descriptions are displayed in C3.

Best,
Mario