Friendly formatting of URNs/channel addresses about goflow HOT 16 CLOSED

Just a quick note that we resolve things like @contact.urns to the first URN a string context, so it would actually be @contact.urns.path.. we also resolve @contact.urns.tel to the first telephone URN. You can also use @contact.urn and just get the highest priority URN, so could be @contact.urn.path.

But ya, so for friendly things, maybe it is something more like @(tel(contact.urn))? No need to pass in the full path if it knows it can be passed an URN.. though it could back down to a string representation if not to let people use the function on their own numbers.

from goflow.

I like the simplicity of tel(...) - I'd assume if you give it something that's not a telephone number it would just return it as is? e.g. @(tel("[email protected]"))

from goflow.

See rapidpro/rapidpro#608

from goflow.

Revisiting this. Given a contact like:

{
  "name": "Billy Bob",
  "urns": ["tel:+250781234567", "twitter:134252511151#billy_bob"]
}

I think the following expressions should evaluate as shown:

@contact.urns -> "+250781234567" // default URN
@contact.urns.scheme -> "tel"
@contact.urns.path -> "+250781234567"
@contact.urns.urn -> "tel:+250781234567"

@contact.urns.tel -> "+250781234567" // first tel URN if there are multiple
@contact.urns.tel.scheme -> "tel"
@contact.urns.tel.path -> "+250781234567"
@contact.urns.tel.display -> "+250781234567"
@contact.urns.tel.urn -> "tel:+250781234567"

@contact.urns.twitter -> "billy_bob"
@contact.urns.twitter.scheme -> "twitter"
@contact.urns.twitter.path -> "134252511151"
@contact.urns.twitter.display -> "billy_bob"
@contact.urns.twitter.urn -> "twitter:134252511151#billy_bob"

@(format_tel(contact.urns.tel)) -> "078 123 4567"
@(format_tel(channel.address)) -> "078 444 8888"

@nicpottier?

from goflow.

Should it be format_tel or format_urn? Seems the former is harder to use as then you need to switch on the type of URN. (though could see the argument for having the latter in addition perhaps?)

Seems slightly weird to me to have @contact.urns return just the path as opposed to the full URN. If it returned the full urn, then you could do @(format_urn(contact.urns)) and have that always do the right thing which seems a lot more useful.

Is the though to get the second tel then something like @contact.urns.tel.1?

from goflow.

I also like .urns returning the full urn because it gets rid of the stutter of @contact.urns.urn

from goflow.

I guess that comes down to whether we want @contact.urns.tel to print as a telephone number, @contact.urns.twitter as a twitter handle... or require users to always use something like @(format_urn(contact.urns.tel)).

Another advantage of format_tel is that it would work with tel numbers in other places (e.g. channel.address, phone numbers in contact fields)

Not completely opposed to format_urn but I think we'd want to bring the old world forward if we went this way - like how we did with format_location and format_datetime

from goflow.

Ya to me these are urns and starting to confuse that concept is going to get confusing for everyone. If we "default" to passing only some of the information, then it seems more likely the user is going to mess things up and only pass us the path which isn't enough to tell whether it is a phone number or something else.

They are going to need to format it either way since the path isn't friendly, so having a full URN makes that formatting easier, because we know the type of the URN to do the right kind of formatting.

Basically I see three options (and we want to be consistent with how contact.urns resolves vs how contact.urns.tel resolves):

1. format.urns resolves to a friendly path. pluses are that's easy to insert into messages, minuses is that that phone number wont work when when passed to other things, saving to fields etc.. because we don't have enough information.

2. format.urns resolves to the path. plus is you have enough if you know it is a telephone number to make it useful for addressing, minuses are that you need to figure out it is a telephone number to format it, and you need to format it to display to the user.

3. format.urns resolves to the full urn. plus is you lose no information, minus is you always need to pass to format_urn. To me this is the most consistent with how we are treating dates, times, locations etc.. which URNs really are just another field on contact so that's a good argument for it.

Would expect that we wrap existing references to @contact.tel in format_urn in our migration, yes.

from goflow.

It's not so different to @contact resolving to the name of the contact... but I guess that's kinda confusing so maybe not a great precedent to follow. Ok so going with format_urn, how does this look:

@contact.urns -> "tel:+250781234567" // default URN
@contact.urns.scheme -> "tel"
@contact.urns.path -> "+250781234567"
@contact.urns.urn -> "tel:+250781234567"

@contact.urns.tel -> "tel:+250781234567" // first tel URN if there are multiple
@contact.urns.tel.scheme -> "tel"
@contact.urns.tel.path -> "+250781234567"
@contact.urns.tel.display -> "+250781234567"
@(format_urn(contact.urns.tel)) -> "078 123 4567"

@contact.urns.twitter -> "twitter:134252511151#billy_bob"
@contact.urns.twitter.scheme -> "twitter"
@contact.urns.twitter.path -> "134252511151"
@contact.urns.twitter.display -> "billy_bob"
@(format_urn(contact.urns.twitter)) -> "billy_bob"

@contact.urns.0 -> "tel:+250781234567"
@contact.urns.1 -> "twitter:134252511151#billy_bob"
@contact.urns.tel.0 -> "tel:+250781234567"

And I need to clarify which migration we're talking about - can we convert to this in the old world like we did with format_datime and format_lcoation, or do you mean the old->new migration in goflow?

from goflow.

Looks good.

Ya, I was thinking more old to new.

from goflow.

Now I'm having second thoughts about things like @contact.urns trying to be both a list and a single URN. Maybe we should make that more explicit too, so..

@contact.urns -> ["tel:+250781234567", "twitter:134252511151#billy_bob"]
@contact.urns.tel -> "tel:+250781234567" // first tel URN
@contact.urns.twitter -> "twitter:134252511151#billy_bob"
@contact.urns.0 -> "tel:+250781234567"
@contact.urns.1 -> "twitter:134252511151#billy_bob"

@contact.urns.xxxx -> error ?
@contact.urns.2 -> error ?

It's certainly possible that a user might want all URNs (e.g. @(JSON(contact.urns))) so it seems weird for @contact.urns to sometimes be a single URN. @contact.urns.0 is at least explicit that we want the highest priority URN.

from goflow.

Well if we did that I would find it confusing that @contact.urns and @contact.tel are not both lists.. that seems super inconsistent.

Can format_urn be smart and only format the first if passed a list? that would allow for both behaviors..

from goflow.

Not as confusing as @contact.urns being a single URN, but I'd be ok with @contact.urns.tel being a list and @contact.urns.tel.0 being the first tel URN. Only complication there is how auto-complete would work in the editor.

I'm imagining as well that the default stringify of a list would be CSV, so for the common case of contacts with single telephone numbers, a user could write @contact.urns.tel and still get a single phone number.

from goflow.

Well @contact.urns.tel would be a list of full URNS though ya?

So for the single case it would be tel:+250788383383 correct?

I still thing FORMAT_URN should accept a list, as the case above in Excellent land is still a list of length 1.

from goflow.

Yes @contact.urns.tel are gonna be full URNs. Fine with having format_urn be flexible.

from goflow.

Added in #145

from goflow.